add readme reconsiliation

README.md

@@ -8,9 +8,13 @@ Generate markdown documentation from directory structure. Optimized for LLM inge
 
 - Recursive directory traversal
 - ASCII tree visualization (LLM-friendly, minimal token overhead)
+- Full tree in every generated file — navigate from anywhere, no matter how deep you are
+- Filtered files and directories stay visible in the tree with annotations (`~ ignored`, `~ tests omitted`)
+- Flags provenance block: every generated file records which filters were active
 - Full file contents with explicit delimiters and metadata
 - Filters dotfiles, binaries, and blacklisted extensions
-- Vertical slices mode: root file + one markdown per top-level directory
+- Vertical slices mode: index file + root slice + one markdown per top-level directory
+- Pick mode: include specific individual files alongside the slices
 - Append mode for single files or directories
 - Force overwrite of existing output files
 - Configurable depth, file size limits, ignore patterns
@@ -83,6 +87,14 @@ dirmd -o "/tmp/${REPO_NAME}" "$REPO_ROOT" -f --vertical-slices --proton-drive
     # Combine filters
     dirmd -o output.md ~/repos/myproject --frontend-only --omit-test
 
+    # Pick specific files alongside vertical slices
+    dirmd -o output.md ~/repos/myproject --vertical-slices \
+        --pick common/src/config.rs --pick init/src/main.rs
+
+    # Same, with a compact breadcrumb instead of the full tree in pick files
+    dirmd -o output.md ~/repos/myproject --vertical-slices \
+        --pick common/src/config.rs --small-tree
+
     # Generate and upload to Proton Drive (default: /my-files/md/<filename>)
     dirmd -o output.md ~/repos/myproject --proton-drive
 
@@ -101,6 +113,8 @@ The `--omit-test` flag removes test files and inline test blocks to reduce token
 
 The Rust stripping works by detecting the `#[cfg(test)]` attribute, then tracking brace depth until the module closes. Nested braces in string literals may occasionally throw off the count, but this is acceptable for RAG use cases.
 
+Omitted test files and directories remain visible in the directory tree with a `~ tests omitted (--omit-test)` annotation, so consumers of the snapshot know they exist and can request them.
+
 ## Frontend Filtering
 
 Two complementary flags control frontend file inclusion:
@@ -126,17 +140,35 @@ Frontend extensions covered:
 
 When `--vertical-slices` is passed, dirmd splits output into multiple files instead of one monolithic document:
 
-- **Root file** (`-o output.md`): Full directory tree with cross-references to slice files, a vertical slices index table (file counts, total bytes per directory), and full contents of all root-level files.
+- **Index file** (`index_<repo>.md`): timestamp, commit, `.dirmd` instructions (if `--instructions`), flags block, full directory tree with annotations and cross-references to slice files, and the vertical slices index table. Deliberately thin — no file contents. This is the always-load document.
-- **Slice files** (`cmd.md`, `internal.md`, etc.): One per top-level directory, placed alongside the root file. Each contains its own tree, a back-reference to the root document, and full recursive file contents for that directory.
+- **Root slice** (`root_<repo>.md`): contents of all root-level files (README, Cargo.toml, justfile, etc.). Selectable like any other slice.
+- **Slice files** (`<dir>/<dir>_<repo>.md`): one per top-level directory, placed in a subdirectory named after it. Each carries the full project tree (not just its subtree), a back-reference to the root document, the flags block, and full recursive file contents for that directory.
+
+Every generated file carries the **full project tree**, so navigation works no matter which file is loaded. Directories excluded via `--ignore` appear as a single collapsed node annotated `~ ignored (--ignore)` — never recursed into — and files filtered by `--omit-test`, `--omit-md`, or frontend flags appear annotated instead of vanishing. The tree tells the consumer what exists but was left out.
 
 This mode cannot be combined with `--append` or `--input-file`.
 
-Example output with `dirmd -o docs.md ~/repos/myproject --vertical-slices`:
+Example output with `dirmd -o docs ~/repos/myproject --vertical-slices`:
 
     docs/
-    ├── docs.md          ← root: tree + slices index + root file contents
+    ├── index_myproject.md      ← index: metadata + tree + slices table
-    ├── cmd.md           ← slice: tree + contents of cmd/
+    ├── root_myproject.md       ← root files (README, etc.)
-    └── internal.md      ← slice: tree + contents of internal/
+    ├── cmd/
+    │   ├── cmd_myproject.md    ← slice: full tree + contents of cmd/
+    │   └── main.rs.md          ← pick file (only if --pick was used)
+    └── internal/
+        └── internal_myproject.md
+
+## Pick Mode
+
+`--pick <path>` selects individual files for inclusion in a sliced run. Repeatable. Requires `--vertical-slices`.
+
+- Picks are written to `<output>/<first-path-segment>/<basename>.md` — e.g. `--pick common/src/config.rs` produces `common/config.rs.md` beside the `common` slice. Root-level picks land directly in the output directory.
+- Every pick run regenerates the full snapshot (slices + picks); a pick run costs one full generation. This keeps the output directory a consistent snapshot of one run.
+- Pick files carry the same metadata block (timestamp, commit, flags) as slices, plus the full project tree by default. With `--small-tree`, the tree is replaced by a breadcrumb line (`Tree: myproject / common / src / config.rs`).
+- Pick files never carry `.dirmd` instructions — those live in the index only.
+- Pick paths must be files, must exist, and must not be excluded by active filters (`--ignore`, `--omit-test`, extension skips). Violations fail the run.
+- Picks are listed in a dedicated `## Picks` section in the index file.
 
 ## Instructions File (`.dirmd`)
 
@@ -149,6 +181,7 @@ This is useful for injecting specific context, constraints, or instructions for
 - **Format**: Plain text or Markdown.
 - **Output**: Rendered as a quoted block (`> Instructions: ...`) immediately after the timestamp and commit info.
 - **Opt-in**: The file is **ignored** unless `--instructions` is explicitly passed.
+- **Scoping**: In vertical slices mode, instructions appear **only in the index file** — never in slice or pick files. One authoritative copy.
 
 Example `.dirmd`:
 
@@ -164,10 +197,12 @@ Output is designed for RAG ingestion and LLM context windows, not human presenta
 
 - **ISO 8601 Timestamp**: Added as a metadata line (`> Generated: ...`) immediately after the H1 header for every new file created.
 - **Git Commit Info**: If the source directory is a Git repository, a second metadata line (`> Commit: <sha> (<message>)`) is added below the timestamp.
+- **Flags provenance block**: `> Flags: --omit-test --skip-frontend` plus lines for extra ignore patterns and skipped extensions. Appears in every generated file so any file in isolation reveals how the snapshot was produced and what to assume exists but was excluded.
+- **Annotated full tree**: same complete tree in every file, with filtered entries annotated (`~ ignored`, `~ tests omitted`) instead of silently dropped
 - **ASCII tree format** (`+-` instead of Unicode box-drawing) to reduce token overhead
 - **Explicit file delimiters**: `--- FILE: ./path (bytes, lines) ---` and `--- END FILE ---`
 - **Document type markers**: `[ROOT]` and `[SLICE]` in H1 headers
-- **Cross-references**: Directory entries in root tree show `-> see cmd.md`; slice files reference their root document
+- **Cross-references**: Directory entries in the tree show `-> see cmd/cmd_myproject.md`; slice and pick files reference their root document
 - **Slices index table**: File counts and total bytes per slice for informed retrieval decisions
 - **Tilde fences** (`~~~`) to avoid conflicts with backticks in source files
 
@@ -179,7 +214,10 @@ Output is designed for RAG ingestion and LLM context windows, not human presenta
 | `-a`, `--append` | Append to existing output file | false |
 | `-f`, `--force` | Overwrite existing output file (non-append mode) | false |
 | `-i`, `--input-file` | Single file input (append mode only) | |
-| `--vertical-slices` | Split output into root file + one markdown per top-level directory | false |
+| `--vertical-slices` | Split output into index + root slice + one markdown per top-level directory | false |
+| `--pick` | Relative path to a file to include as pick (repeatable, requires `--vertical-slices`) | |
+| `--small-tree` | Use breadcrumb instead of full tree in pick files | false |
+| `--instructions` | Include `.dirmd` instructions file if present in root (index file only) | false |
 | `--max-size` | Max file size in bytes | 524288 |
 | `--max-depth` | Max directory recursion depth | 20 |
 | `--ignore` | Additional ignore patterns (glob) | |
@@ -189,12 +227,13 @@ Output is designed for RAG ingestion and LLM context windows, not human presenta
 | `--skip-frontend` | Omit frontend file types (.html, .css, .js, .ts, .vue, .svelte, etc.) | false |
 | `--frontend-only` | Include only frontend file types and README.md | false |
 | `--omit-test` | Exclude test files (Go *_test.go, Java *Test.java) and strip #[cfg(test)] blocks from Rust | false |
+| `--omit-md` | Omit all .md files except README.md | false |
 
 ## Proton Drive Integration
 
 dirmd can optionally upload the generated markdown file(s) to Proton Drive using the [Proton Drive CLI](https://proton.me/support/drive-cli). The upload is performed only when `--proton-drive` is passed. Without it, dirmd behaves exactly as before — no Proton Drive dependency is required.
 
-In vertical slices mode, all generated files (root + slices) are uploaded to `/my-files/md/`. The `--drive-path` flag is ignored in slices mode ; each file is uploaded by its basename.
+In vertical slices mode, the entire output directory (index + root slice + slices + picks) is uploaded to `/my-files/md/<basename>`. The `--drive-path` flag is ignored in slices mode ; each file is uploaded by its basename.
 
 ### Prerequisites
 
@@ -218,22 +257,27 @@ For full documentation on the Proton Drive CLI, including installation, authenti
     dirmd -o output.md ~/repos/project --extensions .log --extensions .tmp
 
     # Vertical slices with overwrite
-    dirmd -o docs.md ~/repos/project -f --vertical-slices
+    dirmd -o docs ~/repos/project -f --vertical-slices
 
     # Skip frontend and omit tests
-    dirmd -o docs.md ~/repos/project -f --skip-frontend --omit-test
+    dirmd -o docs ~/repos/project -f --skip-frontend --omit-test
 
     # Frontend only with test omission
-    dirmd -o docs.md ~/repos/project -f --frontend-only --omit-test
+    dirmd -o docs ~/repos/project -f --frontend-only --omit-test
+
+    # Full snapshot workflow with picks
+    dirmd -o docs ~/repos/project -f --vertical-slices --instructions \
+        --omit-test --skip-frontend \
+        --pick common/src/config.rs --pick mssql-extractor/src/processor.rs
 
     # Generate, then upload to default remote location
-    dirmd -o docs.md ~/repos/project --proton-drive
+    dirmd -o output.md ~/repos/project --proton-drive
 
     # Generate, then upload to a custom remote location
-    dirmd -o docs.md ~/repos/project --proton-drive --drive-path /my-files/projects/docs.md
+    dirmd -o output.md ~/repos/project --proton-drive --drive-path /my-files/projects/docs.md
 
     # Overwrite existing local file and upload to Drive
-    dirmd -o docs.md ~/repos/project -f --proton-drive
+    dirmd -o output.md ~/repos/project -f --proton-drive
 
 ## Output Format
 
@@ -241,17 +285,19 @@ Produces markdown with:
 
 1. Absolute path as H1 header with `[ROOT]` or `[SLICE]` marker
 2. **Timestamp metadata line** (ISO 8601) immediately after the H1 header (only for new files)
-3. ASCII directory tree (indented with `+-` and `|` characters)
+3. **Flags provenance block** (`> Flags: ...`, `> Ignored: ...`, `> Skipped extensions: ...`) when non-default filters are active
-4. Vertical slices index table (sliced mode only)
+4. ASCII directory tree (indented with `+-` and `|` characters), full project tree with annotations for filtered entries, identical in every file of a run
-5. All text files with content in fenced code blocks
+5. Vertical slices index table and picks section (sliced mode only)
-6. Explicit `--- FILE: ---` and `--- END FILE ---` delimiters with byte and line counts
+6. All text files with content in fenced code blocks
-7. Language detection from file extensions
+7. Explicit `--- FILE: ---` and `--- END FILE ---` delimiters with byte and line counts
+8. Language detection from file extensions
 
 Example output structure (non-sliced mode):
 
     # /home/user/repos/myproject [ROOT]
     > Generated: 2026-09-02T14:30:00Z
     > Commit: a1b2c3d (Fix login bug)
+    > Flags: --omit-test
 
     ## Directory Tree
 
@@ -261,7 +307,10 @@ Example output structure (non-sliced mode):
     |   +- main.go
     +- internal/
     |   +- config.go
+    |   +- config_test.go ~ tests omitted (--omit-test)
+    +- target/ ~ ignored (--ignore)
     ~~~
+    Legend: ~ ignored | ~ tests omitted | ~ omitted | ~ exceeded --max-depth
 
     ## Contents