import-ftr

Import existing documentation files into `for-the-record/docs/`. The user specifies where to import from -- there is no default source directory. Generates proper frontmatter for each imported file. Load Configuration

<load-config>
  <action>Resolve the user's home directory.</action>
  <command language="bash" output="home" tool="Bash">echo $HOME</command>
  <constraint>Never pass `~` to the Read tool.</constraint>

  <read path="<home>/.things/config.json" output="config" />
  <if condition="config-missing">Tell the user: "Run `/things:setup-things` first." Then stop.<exit /></if>

  <read path="<home>/.things/for-the-record/preferences.json" output="preferences" />
  <if condition="preferences-missing">Tell the user: "Run `/setup-ftr` first." Then stop.<exit /></if>
</load-config>

Get Source Directory

<if condition="path-argument-provided">
  <action>Use the provided path as the source directory.</action>
</if>

<if condition="no-path-argument">
  <ask-user-question>
    <question>Where are the files you'd like to import?</question>
  </ask-user-question>
</if>

<action>Verify the path exists and is a directory.</action>
<if condition="path-not-found">Tell the user: "Directory not found: <path>." Then stop.<exit /></if>

Scan Source Directory

<action>Scan the source directory for `.md` files. For each file, read the first ~10 lines to extract a brief description (first heading or first paragraph).</action>

<if condition="no-files-found">Tell the user: "No markdown files found in <path>." Then stop.<exit /></if>

<action>Show a numbered list:</action>
<output>
Files found in <source_dir>:
  1. filename.md -- "Brief description from content"
  2. another-file.md -- "Brief description"
  ...
</output>

<ask-user-question>
  <question>Which files would you like to import? Enter numbers (e.g., "1,3,5"), a range (e.g., "1-5"), or "all".</question>
</ask-user-question>

<if condition="--dry-run">
  <action>Show what WOULD happen for each selected file (generated filename, inferred tags, title) but don't write anything. Stop here.</action>
</if>

Import Selected Files

<action>For each selected file:</action>

1. Read the full content
2. Check if it already has YAML frontmatter
   - If yes: preserve existing frontmatter, add any missing required fields (`date`, `tags`)
   - If no: generate frontmatter:
     - `title`: from first `#` heading, or from filename (de-slugified)
     - `date`: from file modification time (`stat -f %Sm -t %Y-%m-%d <file>` on macOS)
     - `description`: first non-heading paragraph, truncated to 2 sentences
     - `detail_level`: `"detailed"` (imported files are typically full documents)
     - `source_type`: `"import"`
     - `tags`: auto-generated from content (technologies, keywords)
3. Generate filename: `<date>-<slugified-title>.md`
4. Write to `<home>/.things/for-the-record/docs/<filename>`

<constraint>Do not delete source files. Imports are copies.</constraint>

Handle Git Workflow

<git-workflow>
  <action>Read git workflow from `config.json` (`git.workflow`).</action>

  <if condition="workflow-auto">Automatically `git add`, `git commit -m "import: <N> documents into for-the-record"`, and `git push`.</if>
  <if condition="workflow-ask">
    <ask-user-question>
      <question>Commit and push the imported documents?</question>
      <option>Yes -- commit and push</option>
      <option>Commit only</option>
      <option>No -- I'll handle git myself</option>
    </ask-user-question>
  </if>
  <if condition="workflow-manual">Tell the user the files have been saved.</if>
</git-workflow>

Confirm

<completion-message>
Imported <N> documents into for-the-record:

<list of imported files with their generated titles and tags>

Find them: `/things:search-things --tag <tag>` or browse `~/.things/for-the-record/docs/`
</completion-message>