siftcode 0.3.0__tar.gz → 0.4.0__tar.gz

{siftcode-0.3.0 → siftcode-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: siftcode
-Version: 0.3.0
+Version: 0.4.0
 Summary: Local LLM-powered code analysis and developer guide generator
 Author-email: Tuomas Lähteenmäki <lahtis@gmail.com>
 License-Expression: GPL-3.0-or-later
@@ -14,14 +14,16 @@ Classifier: Environment :: X11 Applications :: GTK
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Documentation
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.31
-Requires-Dist: PyGObject>=3.46
 Requires-Dist: platformdirs>=4.0
 Requires-Dist: tomli-w>=1.0
+Provides-Extra: gui
+Requires-Dist: PyGObject>=3.46; extra == "gui"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.4; extra == "dev"
 Requires-Dist: pytest-cov>=4.1; extra == "dev"
@@ -71,11 +73,10 @@ generated in minutes.
 - **Project-wide context**: file analyses see the root summary and
   sibling files, producing coherent guides
 - **Progress feedback**: a live progress bar and log during analysis
-- **Cancellable**: stop an analysis mid-run without losing your work
 - **Configurable per project**: model, context size, temperature, file
   exclusions, and cache settings are all saved per project
 - **Two front-ends**: a modern GTK4 + libadwaita GUI and a scriptable CLI
-- **Tested**: 200+ unit tests, ~95 % coverage in the core
+- **Tested**: 353 unit tests, 79 % overall coverage (88–100 % for core modules)
 
 ---
 
@@ -102,8 +103,8 @@ generated in minutes.
 
 - **Linux** (X11 or Wayland)
 - **Python 3.11** or newer
-- **GTK 4.10+** and **libadwaita 1.4+**
-- **[Ollama](https://ollama.com)** running locally
+- **GTK 4.10+** and **libadwaita 1.5+** (for the GUI)
+- **[Ollama](https://ollama.com)** 0.1.24 or newer, running locally
 - A code-capable LLM installed via Ollama, for example:
 
   ```bash
@@ -119,12 +120,20 @@ GPU and the model you choose.
 |---|---|---|---|---|
 | `qwen2.5-coder:7b` | ~5 GB | ~3 min | Basic | Small projects, laptops |
 | **`qwen2.5-coder:14b`** | **~10 GB** | **~7 min** | **Good** | **Recommended default** |
-| `qwen2.5-coder:32b` | ~22 GB | ~33 min | Excellent | Workstations, best quality |
+| `qwen2.5-coder:32b` | ~22 GB | ~33 min | Excellent | 24 GB+ GPUs, best quality |
+
+**Quick rule of thumb by VRAM:**
+
+- **< 8 GB** → use `7b`, or accept slow CPU-only runs
+- **8–16 GB** → use `14b`; it's the sweet spot for most projects
+- **24 GB+** → use `32b`. It fits comfortably (e.g. Quadro P6000,
+  RTX 3090, RTX 4090) and produces noticeably fewer hallucinations —
+  in particular it stops inventing files like `setup.py` in modern
+  `pyproject.toml` projects.
 
 For CUDA GPUs, ensure your driver is recent enough for your Ollama
 build. CPU-only operation works but is slow (expect 5–15× longer runs).
 
-
 **Observations from real runs:**
 
 - **14B** produces a comprehensive guide in ~7 minutes. It occasionally
@@ -135,45 +144,148 @@ build. CPU-only operation works but is slow (expect 5–15× longer runs).
   concise and may skip smaller files.
 - **7B** is useful for small projects or when you need a quick pass.
 
-**Tip:** With 32 GB+ RAM and a workstation-class GPU, you can keep
-both 14B and 32B loaded at the same time:
+### Context length
+
+The default `num_ctx` is **8192** tokens, which fits the default 14B
+model on a 10 GB GPU comfortably.
+
+**When to raise it:** The guide generation prompt includes the root
+summary, all directory summaries, and all file summaries. For a
+40-file project, this can be ~23,000 tokens. With `num_ctx=8192`,
+Ollama truncates the context and the model may not see most of the
+files — the guide ends up mentioning only a handful of modules.
+
+If you have the VRAM, raise it per project:
+
+```bash
+siftcode analyze myproject --num-ctx 32768
+```
+
+### Multi-model support
+
+Different analysis stages have different needs. Per-file summaries
+are simple tasks where a small model excels; the root summary and
+the final guide require broader reasoning and benefit from a larger
+model. Siftcode lets you assign a different model to each stage.
+
+Stages: `root`, `file`, `directories`, `guide`.
+
+**With a 24 GB GPU** (Quadro P6000, RTX 3090, RTX 4090), the best
+configuration is:
+
+```bash
+siftcode analyze myproject \
+  --model-stage root=qwen2.5-coder:32b \
+  --model-stage guide=qwen2.5-coder:32b
+```
+
+This takes ~9 minutes instead of ~33 (32B on every file) or
+~7 (14B everywhere), and gives most of the quality benefit: the
+32B model handles the two stages where its broader reasoning
+matters most, while 14B handles the file summaries where speed
+matters more than depth.
+
+Persist the configuration so you don't have to type it every
+time — the stage overrides are saved to the project's TOML file:
+
+```bash
+siftcode analyze myproject --model-stage guide=qwen2.5-coder:32b
+siftcode show myproject
+```
+
+```text
+  Model:
+    Name:        qwen2.5-coder:14b
+    Stages:
+      root         (default)
+      file         (default)
+      directories  (default)
+      guide        qwen2.5-coder:32b
+    Ollama URL:  http://127.0.0.1:11434
+    num_ctx:     8192
+    spec_num_ctx: 16384
+    temperature: 0.0
+    timeout:     600s
+     
+```
+You can also edit the TOML directly:
+```toml
+[model]
+name = "qwen2.5-coder:14b"
+
+[model.stages]
+root  = "qwen2.5-coder:32b"
+guide = "qwen2.5-coder:32b"
+```
+How the cache behaves: the cache is keyed per model, so
+switching a single stage's model does not invalidate the other
+stages' cached results. If you later re-run with the same stage
+models, the previous summaries are reused — you only pay for the
+stages you actually changed.
+
+Shortcut: to use the same model for every stage, use --model:
+```bash
+siftcode analyze myproject --model qwen2.5-coder:32b
+```
+
+**Tip — keeping both models loaded:** If you have enough VRAM to
+hold both 14B and 32B simultaneously (~32 GB VRAM total), you can
+avoid model reloads between stages:
 
 ```bash
 export OLLAMA_MAX_LOADED_MODELS=2
 export OLLAMA_KV_CACHE_TYPE=q8_0
 ```
 
-This lets you use 14B for quick iterations and 32B for the final
-guide without reloading models from disk.
+---
 
-For CUDA GPUs, ensure your driver is recent enough for your Ollama
-build. CPU-only operation works but is slow (expect 5–15× longer runs).
+### Advanced per-file specifications (`--advanced`)
 
-### Recommended context length
+The `--advanced` flag generates a detailed technical specification for
+each source file instead of the usual developer guide. Specs are much
+longer than regular file summaries, so they use a separate context
+length: `spec_num_ctx` (default **16384**).
+
+**On a 24 GB GPU**, 32B Q4_K_M plus a 16k KV cache is right at the
+VRAM limit — Ollama offloads ~4% of the model to the CPU, which roughly
+doubles the run time. Lowering the spec context to 12k keeps the whole
+model on the GPU:
+
+```bash
+siftcode analyze myproject --advanced \
+  --model-stage file=qwen2.5-coder:32b \
+  --spec-num-ctx 12288
+```
 
-The default `num_ctx` has been increased from 8192 to 32768
-tokens.
+Verify with `ollama ps`: the `PROCESSOR` column should read `100% GPU`.
+If it shows any CPU percentage, lower `--spec-num-ctx` further
+(10240, 8192) until the model fits entirely on the GPU.
 
-**Why:** The guide generation prompt includes the root summary,
-all directory summaries, and all file summaries. For a 40-file
-project, this is roughly 23,000 tokens. With `num_ctx=8192`,
-Ollama truncates the context and the model never sees most of
-the files — the guide ends up mentioning only a handful of
-modules.
+`spec_num_ctx` is saved per project, so you only need the flag once:
 
-**Verification:** A real-world 40-file Python project required
-23,575 tokens for complete context. With `num_ctx=32768`, the
-generated guide mentions 20+ modules including `analyzer.py`,
-`cache.py`, `cli.py`, and all GUI views.
+```bash
+siftcode analyze myproject --advanced \
+  --model-stage file=qwen2.5-coder:32b \
+  --spec-num-ctx 12288
+siftcode show myproject
+# → spec_num_ctx: 12288
+```
 
-**VRAM:** With 14B Q4_K_M + `OLLAMA_KV_CACHE_TYPE=q8_0`, VRAM
-usage is ~13 GB. Comfortably within 24 GB.
+> **Note:** `--advanced` mode with a 32B model is very slow (one
+> document per file, each taking 10+ minutes on a 24 GB GPU). For
+> projects with more than ~10 files, use the default 14B model:
+>
+>     siftcode analyze myproject --advanced
 
 ---
 
 ## Installation
+```bash
+pip install siftcode
+```
+> Note: the GTK GUI requires system packages listed under System dependencies. The CLI works without them
 
-### From source (recommended for now)
+### Development installation
 
 ```bash
 git clone https://codeberg.org/lahtis/siftcode.git
@@ -187,8 +299,6 @@ pip install -e ".[dev]"
 
 ```bash
 siftcode --version
-# → siftcode 0.3.0
-
 siftcode about
 # → prints version, author, and license
 ```
@@ -244,6 +354,11 @@ siftcode analyze "My Project" --output ~/siftcode-output
 # Analyze it with advanced per-file technical specifications
 siftcode analyze "My Project" --output ~/siftcode-output --advanced
 
+# Advanced + multi-model: 32B for specs, 14B for the rest
+siftcode analyze "My Project" --advanced \
+  --model-stage file=qwen2.5-coder:32b \
+  --spec-num-ctx 12288
+
 # Delete a project
 siftcode delete "My Project"
 ```
@@ -268,11 +383,11 @@ siftcode cache gc --days 30         # prune entries unused for 30 days
 
 ### Output
 
-Analysis produces two files in the output directory:
+Analysis produces these files in the output directory:
 
-- `findings.json` — raw structured findings (root, directories, files, errors)
-- `guide.md` — the generated developer guide
-- `docs/specs/` — advanced per-file technical specifications (when `--advanced` is used)
+- `findings_<project>_<timestamp>.json` — raw structured findings (root, directories, files, errors)
+- `guide_<project>_<timestamp>.md` — the generated developer guide
+- `specs_<project>_<timestamp>/` — advanced per-file technical specifications (when `--advanced` is used)
 
 ---
 
@@ -304,6 +419,22 @@ human-readable and can be edited by hand if you prefer.
 
 ---
 
+### Default exclusions
+
+The default exclusion list already covers:
+
+- Version control directories (`.git`, `.venv`, `node_modules`)
+- Build artifacts (`build`, `dist`, `.pytest_cache`)
+- Documentation directories (`docs`, `doc`)
+- Binary file suffixes (`.png`, `.jpg`, `.zip`, `.so`)
+- **Database files** (`.sqlite`, `.sqlite3`, `.db`, `.db3`, `.mdb`)
+- Editor configs (`.editorconfig`, `.env`)
+
+You can add or remove patterns per project from the GUI, or by editing
+the `analysis.exclude` list in the project's TOML file.
+
+---
+
 ## How it works
 
 1. **Root analysis** — the LLM sees the project tree and infers the
@@ -315,13 +446,32 @@ human-readable and can be edited by hand if you prefer.
 4. **Guide generation** — all of the above is composed into a
    structured Markdown developer guide.
 5. **Advanced specs (optional)** — when `--advanced` is used, individual
-   per-file technical specifications are generated and stored in `docs/specs/`.
+   per-file technical specifications are generated and stored in `specs_<project>_<timestamp>/`.
 
 Each step is cached by SHA-256 hash of the input. When you re-run on an
 unchanged project, only the guide is regenerated.
 
 ---
 
+### Beyond documentation: spec-driven development
+
+Because `--advanced` produces per-file technical specifications in Markdown
+(`specs_<project>_<timestamp>/`), the output can be used as an implementation spec — not just
+as documentation.
+
+Feed `guide_<project>_<timestamp>.md` and the `specs_<project>_<timestamp>/` directory to an AI coding assistant and ask it to build the project from scratch. The result is a new codebase that follows the original architecture and interfaces. This makes Siftcode useful not only for understanding existing code, but also for:
+
+- **Porting** a project to another language — the specs are language-agnostic
+- **Rebuilding** a project on a clean foundation — same design, new implementation
+- **Starting from a spec** — write or generate the specs first, then let the AI implement them
+
+> **Note:** Specs are generated by an LLM and may contain inaccuracies
+> (the 14B model occasionally invents files that don't exist). Review them
+> before using them as an implementation spec. Larger models produce more
+> accurate specs.
+
+---
+
 ## Development
 
 ```bash
@@ -341,6 +491,9 @@ ruff check src/ tests/
 # Type-check
 mypy src/
 ```
+> Note: GUI tests require a display. Use xvfb-run in headless
+environments; they are skipped automatically when no display is
+available.
 
 ### Project layout
 
@@ -355,7 +508,7 @@ siftcode/
 │   │   ├── config.py     # project configuration
 │   │   ├── llm.py        # Ollama client
 │   │   ├── prompts.py    # prompt templates
-│   │   └── manual.py     # Advanced Technical Analysis & Specification Generator
+│   │   └── manual.py     # advanced specification generator
 │   └── gui/              # GTK4 front-end
 │       ├── app.py
 │       ├── window.py

{siftcode-0.3.0 → siftcode-0.4.0}/README.md

@@ -40,11 +40,10 @@ generated in minutes.
 - **Project-wide context**: file analyses see the root summary and
   sibling files, producing coherent guides
 - **Progress feedback**: a live progress bar and log during analysis
-- **Cancellable**: stop an analysis mid-run without losing your work
 - **Configurable per project**: model, context size, temperature, file
   exclusions, and cache settings are all saved per project
 - **Two front-ends**: a modern GTK4 + libadwaita GUI and a scriptable CLI
-- **Tested**: 200+ unit tests, ~95 % coverage in the core
+- **Tested**: 353 unit tests, 79 % overall coverage (88–100 % for core modules)
 
 ---
 
@@ -71,8 +70,8 @@ generated in minutes.
 
 - **Linux** (X11 or Wayland)
 - **Python 3.11** or newer
-- **GTK 4.10+** and **libadwaita 1.4+**
-- **[Ollama](https://ollama.com)** running locally
+- **GTK 4.10+** and **libadwaita 1.5+** (for the GUI)
+- **[Ollama](https://ollama.com)** 0.1.24 or newer, running locally
 - A code-capable LLM installed via Ollama, for example:
 
   ```bash
@@ -88,12 +87,20 @@ GPU and the model you choose.
 |---|---|---|---|---|
 | `qwen2.5-coder:7b` | ~5 GB | ~3 min | Basic | Small projects, laptops |
 | **`qwen2.5-coder:14b`** | **~10 GB** | **~7 min** | **Good** | **Recommended default** |
-| `qwen2.5-coder:32b` | ~22 GB | ~33 min | Excellent | Workstations, best quality |
+| `qwen2.5-coder:32b` | ~22 GB | ~33 min | Excellent | 24 GB+ GPUs, best quality |
+
+**Quick rule of thumb by VRAM:**
+
+- **< 8 GB** → use `7b`, or accept slow CPU-only runs
+- **8–16 GB** → use `14b`; it's the sweet spot for most projects
+- **24 GB+** → use `32b`. It fits comfortably (e.g. Quadro P6000,
+  RTX 3090, RTX 4090) and produces noticeably fewer hallucinations —
+  in particular it stops inventing files like `setup.py` in modern
+  `pyproject.toml` projects.
 
 For CUDA GPUs, ensure your driver is recent enough for your Ollama
 build. CPU-only operation works but is slow (expect 5–15× longer runs).
 
-
 **Observations from real runs:**
 
 - **14B** produces a comprehensive guide in ~7 minutes. It occasionally
@@ -104,45 +111,148 @@ build. CPU-only operation works but is slow (expect 5–15× longer runs).
   concise and may skip smaller files.
 - **7B** is useful for small projects or when you need a quick pass.
 
-**Tip:** With 32 GB+ RAM and a workstation-class GPU, you can keep
-both 14B and 32B loaded at the same time:
+### Context length
+
+The default `num_ctx` is **8192** tokens, which fits the default 14B
+model on a 10 GB GPU comfortably.
+
+**When to raise it:** The guide generation prompt includes the root
+summary, all directory summaries, and all file summaries. For a
+40-file project, this can be ~23,000 tokens. With `num_ctx=8192`,
+Ollama truncates the context and the model may not see most of the
+files — the guide ends up mentioning only a handful of modules.
+
+If you have the VRAM, raise it per project:
+
+```bash
+siftcode analyze myproject --num-ctx 32768
+```
+
+### Multi-model support
+
+Different analysis stages have different needs. Per-file summaries
+are simple tasks where a small model excels; the root summary and
+the final guide require broader reasoning and benefit from a larger
+model. Siftcode lets you assign a different model to each stage.
+
+Stages: `root`, `file`, `directories`, `guide`.
+
+**With a 24 GB GPU** (Quadro P6000, RTX 3090, RTX 4090), the best
+configuration is:
+
+```bash
+siftcode analyze myproject \
+  --model-stage root=qwen2.5-coder:32b \
+  --model-stage guide=qwen2.5-coder:32b
+```
+
+This takes ~9 minutes instead of ~33 (32B on every file) or
+~7 (14B everywhere), and gives most of the quality benefit: the
+32B model handles the two stages where its broader reasoning
+matters most, while 14B handles the file summaries where speed
+matters more than depth.
+
+Persist the configuration so you don't have to type it every
+time — the stage overrides are saved to the project's TOML file:
+
+```bash
+siftcode analyze myproject --model-stage guide=qwen2.5-coder:32b
+siftcode show myproject
+```
+
+```text
+  Model:
+    Name:        qwen2.5-coder:14b
+    Stages:
+      root         (default)
+      file         (default)
+      directories  (default)
+      guide        qwen2.5-coder:32b
+    Ollama URL:  http://127.0.0.1:11434
+    num_ctx:     8192
+    spec_num_ctx: 16384
+    temperature: 0.0
+    timeout:     600s
+     
+```
+You can also edit the TOML directly:
+```toml
+[model]
+name = "qwen2.5-coder:14b"
+
+[model.stages]
+root  = "qwen2.5-coder:32b"
+guide = "qwen2.5-coder:32b"
+```
+How the cache behaves: the cache is keyed per model, so
+switching a single stage's model does not invalidate the other
+stages' cached results. If you later re-run with the same stage
+models, the previous summaries are reused — you only pay for the
+stages you actually changed.
+
+Shortcut: to use the same model for every stage, use --model:
+```bash
+siftcode analyze myproject --model qwen2.5-coder:32b
+```
+
+**Tip — keeping both models loaded:** If you have enough VRAM to
+hold both 14B and 32B simultaneously (~32 GB VRAM total), you can
+avoid model reloads between stages:
 
 ```bash
 export OLLAMA_MAX_LOADED_MODELS=2
 export OLLAMA_KV_CACHE_TYPE=q8_0
 ```
 
-This lets you use 14B for quick iterations and 32B for the final
-guide without reloading models from disk.
+---
 
-For CUDA GPUs, ensure your driver is recent enough for your Ollama
-build. CPU-only operation works but is slow (expect 5–15× longer runs).
+### Advanced per-file specifications (`--advanced`)
 
-### Recommended context length
+The `--advanced` flag generates a detailed technical specification for
+each source file instead of the usual developer guide. Specs are much
+longer than regular file summaries, so they use a separate context
+length: `spec_num_ctx` (default **16384**).
+
+**On a 24 GB GPU**, 32B Q4_K_M plus a 16k KV cache is right at the
+VRAM limit — Ollama offloads ~4% of the model to the CPU, which roughly
+doubles the run time. Lowering the spec context to 12k keeps the whole
+model on the GPU:
+
+```bash
+siftcode analyze myproject --advanced \
+  --model-stage file=qwen2.5-coder:32b \
+  --spec-num-ctx 12288
+```
 
-The default `num_ctx` has been increased from 8192 to 32768
-tokens.
+Verify with `ollama ps`: the `PROCESSOR` column should read `100% GPU`.
+If it shows any CPU percentage, lower `--spec-num-ctx` further
+(10240, 8192) until the model fits entirely on the GPU.
 
-**Why:** The guide generation prompt includes the root summary,
-all directory summaries, and all file summaries. For a 40-file
-project, this is roughly 23,000 tokens. With `num_ctx=8192`,
-Ollama truncates the context and the model never sees most of
-the files — the guide ends up mentioning only a handful of
-modules.
+`spec_num_ctx` is saved per project, so you only need the flag once:
 
-**Verification:** A real-world 40-file Python project required
-23,575 tokens for complete context. With `num_ctx=32768`, the
-generated guide mentions 20+ modules including `analyzer.py`,
-`cache.py`, `cli.py`, and all GUI views.
+```bash
+siftcode analyze myproject --advanced \
+  --model-stage file=qwen2.5-coder:32b \
+  --spec-num-ctx 12288
+siftcode show myproject
+# → spec_num_ctx: 12288
+```
 
-**VRAM:** With 14B Q4_K_M + `OLLAMA_KV_CACHE_TYPE=q8_0`, VRAM
-usage is ~13 GB. Comfortably within 24 GB.
+> **Note:** `--advanced` mode with a 32B model is very slow (one
+> document per file, each taking 10+ minutes on a 24 GB GPU). For
+> projects with more than ~10 files, use the default 14B model:
+>
+>     siftcode analyze myproject --advanced
 
 ---
 
 ## Installation
+```bash
+pip install siftcode
+```
+> Note: the GTK GUI requires system packages listed under System dependencies. The CLI works without them
 
-### From source (recommended for now)
+### Development installation
 
 ```bash
 git clone https://codeberg.org/lahtis/siftcode.git
@@ -156,8 +266,6 @@ pip install -e ".[dev]"
 
 ```bash
 siftcode --version
-# → siftcode 0.3.0
-
 siftcode about
 # → prints version, author, and license
 ```
@@ -213,6 +321,11 @@ siftcode analyze "My Project" --output ~/siftcode-output
 # Analyze it with advanced per-file technical specifications
 siftcode analyze "My Project" --output ~/siftcode-output --advanced
 
+# Advanced + multi-model: 32B for specs, 14B for the rest
+siftcode analyze "My Project" --advanced \
+  --model-stage file=qwen2.5-coder:32b \
+  --spec-num-ctx 12288
+
 # Delete a project
 siftcode delete "My Project"
 ```
@@ -237,11 +350,11 @@ siftcode cache gc --days 30         # prune entries unused for 30 days
 
 ### Output
 
-Analysis produces two files in the output directory:
+Analysis produces these files in the output directory:
 
-- `findings.json` — raw structured findings (root, directories, files, errors)
-- `guide.md` — the generated developer guide
-- `docs/specs/` — advanced per-file technical specifications (when `--advanced` is used)
+- `findings_<project>_<timestamp>.json` — raw structured findings (root, directories, files, errors)
+- `guide_<project>_<timestamp>.md` — the generated developer guide
+- `specs_<project>_<timestamp>/` — advanced per-file technical specifications (when `--advanced` is used)
 
 ---
 
@@ -273,6 +386,22 @@ human-readable and can be edited by hand if you prefer.
 
 ---
 
+### Default exclusions
+
+The default exclusion list already covers:
+
+- Version control directories (`.git`, `.venv`, `node_modules`)
+- Build artifacts (`build`, `dist`, `.pytest_cache`)
+- Documentation directories (`docs`, `doc`)
+- Binary file suffixes (`.png`, `.jpg`, `.zip`, `.so`)
+- **Database files** (`.sqlite`, `.sqlite3`, `.db`, `.db3`, `.mdb`)
+- Editor configs (`.editorconfig`, `.env`)
+
+You can add or remove patterns per project from the GUI, or by editing
+the `analysis.exclude` list in the project's TOML file.
+
+---
+
 ## How it works
 
 1. **Root analysis** — the LLM sees the project tree and infers the
@@ -284,13 +413,32 @@ human-readable and can be edited by hand if you prefer.
 4. **Guide generation** — all of the above is composed into a
    structured Markdown developer guide.
 5. **Advanced specs (optional)** — when `--advanced` is used, individual
-   per-file technical specifications are generated and stored in `docs/specs/`.
+   per-file technical specifications are generated and stored in `specs_<project>_<timestamp>/`.
 
 Each step is cached by SHA-256 hash of the input. When you re-run on an
 unchanged project, only the guide is regenerated.
 
 ---
 
+### Beyond documentation: spec-driven development
+
+Because `--advanced` produces per-file technical specifications in Markdown
+(`specs_<project>_<timestamp>/`), the output can be used as an implementation spec — not just
+as documentation.
+
+Feed `guide_<project>_<timestamp>.md` and the `specs_<project>_<timestamp>/` directory to an AI coding assistant and ask it to build the project from scratch. The result is a new codebase that follows the original architecture and interfaces. This makes Siftcode useful not only for understanding existing code, but also for:
+
+- **Porting** a project to another language — the specs are language-agnostic
+- **Rebuilding** a project on a clean foundation — same design, new implementation
+- **Starting from a spec** — write or generate the specs first, then let the AI implement them
+
+> **Note:** Specs are generated by an LLM and may contain inaccuracies
+> (the 14B model occasionally invents files that don't exist). Review them
+> before using them as an implementation spec. Larger models produce more
+> accurate specs.
+
+---
+
 ## Development
 
 ```bash
@@ -310,6 +458,9 @@ ruff check src/ tests/
 # Type-check
 mypy src/
 ```
+> Note: GUI tests require a display. Use xvfb-run in headless
+environments; they are skipped automatically when no display is
+available.
 
 ### Project layout
 
@@ -324,7 +475,7 @@ siftcode/
 │   │   ├── config.py     # project configuration
 │   │   ├── llm.py        # Ollama client
 │   │   ├── prompts.py    # prompt templates
-│   │   └── manual.py     # Advanced Technical Analysis & Specification Generator
+│   │   └── manual.py     # advanced specification generator
 │   └── gui/              # GTK4 front-end
 │       ├── app.py
 │       ├── window.py