siftcode 0.3.0__tar.gz → 0.3.1__tar.gz

{siftcode-0.3.0/src/siftcode.egg-info → siftcode-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: siftcode
-Version: 0.3.0
+Version: 0.3.1
 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**: 305 unit tests, 78 % 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
@@ -151,8 +152,7 @@ build. CPU-only operation works but is slow (expect 5–15× longer runs).
 
 ### Recommended context length
 
-The default `num_ctx` has been increased from 8192 to 32768
-tokens.
+The default `num_ctx` is 32768 tokens.
 
 **Why:** The guide generation prompt includes the root summary,
 all directory summaries, and all file summaries. For a 40-file
@@ -172,8 +172,12 @@ usage is ~13 GB. Comfortably within 24 GB.
 ---
 
 ## 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,7 +191,7 @@ pip install -e ".[dev]"
 
 ```bash
 siftcode --version
-# → siftcode 0.3.0
+
 
 siftcode about
 # → prints version, author, and license
@@ -270,9 +274,9 @@ siftcode cache gc --days 30         # prune entries unused for 30 days
 
 Analysis produces two 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)
 
 ---
 
@@ -315,13 +319,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 +364,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 +381,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.3.1}/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**: 305 unit tests, 78 % 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
@@ -120,8 +119,7 @@ build. CPU-only operation works but is slow (expect 5–15× longer runs).
 
 ### Recommended context length
 
-The default `num_ctx` has been increased from 8192 to 32768
-tokens.
+The default `num_ctx` is 32768 tokens.
 
 **Why:** The guide generation prompt includes the root summary,
 all directory summaries, and all file summaries. For a 40-file
@@ -141,8 +139,12 @@ usage is ~13 GB. Comfortably within 24 GB.
 ---
 
 ## 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,7 +158,7 @@ pip install -e ".[dev]"
 
 ```bash
 siftcode --version
-# → siftcode 0.3.0
+
 
 siftcode about
 # → prints version, author, and license
@@ -239,9 +241,9 @@ siftcode cache gc --days 30         # prune entries unused for 30 days
 
 Analysis produces two 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)
 
 ---
 
@@ -284,13 +286,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 +331,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 +348,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.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "siftcode"
-dynamic = ["version"]                      # <-- tämä korvaa version-kentän
+dynamic = ["version"]
 description = "Local LLM-powered code analysis and developer guide generator"
 readme = "README.md"
 license = "GPL-3.0-or-later"
@@ -19,17 +19,27 @@ classifiers = [
     "Intended Audience :: Developers",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Software Development :: Documentation",
 ]
 
+# Core dependencies — the CLI only needs these.
 dependencies = [
     "requests>=2.31",
-    "PyGObject>=3.46",
     "platformdirs>=4.0",
     "tomli-w>=1.0",
 ]
 
 [project.optional-dependencies]
+# The GTK GUI is optional so that headless installs (servers, CI,
+# Docker) don't need to build PyGObject's C dependencies.
+#
+# Requires libadwaita >= 1.5 at the system level (for Adw.AboutDialog).
+# PyGObject does not control the installed libadwaita version — it's
+# provided by the distribution's package manager.
+gui = [
+    "PyGObject>=3.46",
+]
 dev = [
     "pytest>=7.4",
     "pytest-cov>=4.1",
@@ -55,7 +65,6 @@ version = {attr = "siftcode._version.__version__"}
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["siftcode*"]
-exclude = ["tests*"]
 
 [tool.setuptools.package-data]
 siftcode = [

siftcode-0.3.1/src/siftcode/__init__.py

@@ -0,0 +1,5 @@
+"""Siftcode — local LLM-powered code analysis."""
+
+from siftcode._version import __version__
+
+__all__ = ["__version__"]

{siftcode-0.3.0 → siftcode-0.3.1}/src/siftcode/_version.py

@@ -7,9 +7,40 @@ version, name, author, license, and other identifying information.
 
 from __future__ import annotations
 
-__version__ = "0.3.0"
+from typing import Any
+
+
+__all__ = [
+    "__version__",
+    "__version_info__",
+    "__release_date__",
+    "__status__",
+    "APP_ID",
+    "APP_NAME",
+    "APP_SLUG",
+    "APP_TAGLINE",
+    "APP_SUMMARY",
+    "AUTHOR_NAME",
+    "AUTHOR_EMAIL",
+    "COPYRIGHT",
+    "COPYRIGHT_YEAR",
+    "LICENSE_NAME",
+    "LICENSE_SPDX",
+    "LICENSE_URL",
+    "HOMEPAGE_URL",
+    "REPOSITORY_URL",
+    "ISSUES_URL",
+    "CHANGELOG_URL",
+    "DESCRIPTION",
+    "version_string",
+    "short_version",
+    "about_data",
+]
+
+
+__version__ = "0.3.1"
 __version_info__ = tuple(int(p) for p in __version__.split(".") if p.isdigit())
-__release_date__ = "2026-10-16"
+__release_date__ = "2026-10-21"
 __status__ = "beta"
 
 APP_ID = "io.codeberg.lahtis.Siftcode"
@@ -39,19 +70,32 @@ DESCRIPTION = (
     "Everything runs on your own hardware — no code leaves your machine."
 )
 
+
 def version_string() -> str:
+    """Return a human-readable version string, e.g. 'Siftcode 0.3.0 (beta)'."""
     return f"{APP_NAME} {__version__} ({__status__})"
 
+
 def short_version() -> str:
+    """Return just the version number, e.g. '0.3.0'."""
     return __version__
 
-def about_data() -> dict:
+
+def about_data() -> dict[str, Any]:
+    """
+    Return a dictionary of metadata suitable for Gtk.AboutDialog.
+
+    The 'license_type' value is a Gtk.License enum name; 'gpl-3-0-later'
+    matches LICENSE_SPDX = 'GPL-3.0-or-later'. Using 'gpl-3-0' here would
+    incorrectly claim GPL-3.0-only, which is stricter than the project's
+    actual license.
+    """
     return {
         "application_name": APP_NAME,
         "application_icon": APP_ID,
         "version": __version__,
         "developer_name": AUTHOR_NAME,
-        "license_type": "gpl-3-0",
+        "license_type": "gpl-3-0-later",
         "comments": DESCRIPTION,
         "website": HOMEPAGE_URL,
         "issue_url": ISSUES_URL,

{siftcode-0.3.0 → siftcode-0.3.1}/src/siftcode/cli.py

@@ -6,6 +6,7 @@ Provides a thin layer over the core modules:
 - cache: analysis cache management
 - llm: Ollama client
 - analyzer: project analysis engine
+- manual: advanced per-file specification generator
 
 No GTK dependencies.
 """
@@ -14,6 +15,7 @@ from __future__ import annotations
 
 import argparse
 import logging
+import shutil
 import sys
 from datetime import datetime
 from pathlib import Path
@@ -86,6 +88,12 @@ def _resolve_project(name_or_path: str) -> ProjectConfig:
             f"hint: '{name_or_path}' is not a directory and no saved project "
             f"matches. Run '{APP_SLUG} list' to see saved projects."
         )
+    except ValueError as e:
+        # load_project now raises ValueError for malformed TOML files.
+        raise SystemExit(
+            f"error: saved project '{name_or_path}' is invalid: {e}\n"
+            f"hint: fix or delete the config file under {PROJECTS_DIR}"
+        )
 
 
 def _check_ollama(client: OllamaClient) -> None:
@@ -109,11 +117,18 @@ def _print_progress(progress) -> None:
     bar_width = 30
     filled = int(bar_width * progress.fraction)
     bar = "█" * filled + "░" * (bar_width - filled)
-    print(
-        f"  [{bar}] {progress.fraction * 100:5.1f}%  {progress.message}",
-        end="\r" if progress.fraction < 1.0 else "\n",
-        flush=True,
-    )
+    msg = f"  [{bar}] {progress.fraction * 100:5.1f}%  {progress.message}"
+
+    cols = shutil.get_terminal_size().columns
+    if len(msg) > cols - 1:
+        msg = msg[: cols - 4] + "..."
+
+    # Progress bar goes to stderr: visible on screen, but never mixed
+    # into a piped/logged stdout stream. \033[K clears the previous line.
+    print(f"\r\033[K{msg}", end="", file=sys.stderr, flush=True)
+
+    if progress.fraction >= 1.0:
+        print(file=sys.stderr)
 
 
 def _human_size(num_bytes: int) -> str:
@@ -124,6 +139,43 @@ def _human_size(num_bytes: int) -> str:
     return f"{num_bytes:.1f} TB"
 
 
+def _safe_stem(name: str) -> str:
+    """
+    Convert a project name into a filesystem-safe stem.
+
+    Replaces path separators, spaces, and other problematic characters
+    so that a project name like "my/project" doesn't create subdirectories
+    or fail on Windows.
+    """
+    safe = "".join(
+        c if c.isalnum() or c in ("-", "_", ".") else "_"
+        for c in name
+    ).strip("._")
+    return safe or "project"
+
+
+def _stamp() -> str:
+    """Single timestamp used for all output files of one run."""
+    return datetime.now().strftime("%Y%m%d_%H%M%S")
+
+
+def _save_last_run(config: ProjectConfig) -> None:
+    """
+    Persist last_run after a successful analysis.
+
+    Failures are logged but never abort the command: the analysis
+    results are already on disk and more valuable than the timestamp.
+    """
+    config.last_run = datetime.now().isoformat(timespec="seconds")
+    try:
+        save_project(config)
+    except Exception as e:
+        logger.warning(
+            "Could not update last_run for project '%s': %s",
+            config.name, e,
+        )
+
+
 # ---------------------------------------------------------------------------
 # Commands
 # ---------------------------------------------------------------------------
@@ -142,14 +194,22 @@ def cmd_analyze(args: argparse.Namespace) -> int:
     if args.timeout:
         config.model.timeout = args.timeout
 
+    # Validate BEFORE persisting, so we never save a broken config.
+    config.validate()
+
+    # Persist (only if the project already exists as a saved project).
+    # A malformed existing TOML is overwritten with the validated config.
     try:
         load_project(config.name)
         save_project(config)
         logger.info(f"Updated saved project '{config.name}'")
     except FileNotFoundError:
         pass
-
-    config.validate()
+    except ValueError as e:
+        logger.warning(
+            "Existing project config is invalid and will be overwritten: %s", e,
+        )
+        save_project(config)
 
     output_dir = Path(args.output).expanduser() if args.output else Path.cwd()
     output_dir.mkdir(parents=True, exist_ok=True)
@@ -162,56 +222,99 @@ def cmd_analyze(args: argparse.Namespace) -> int:
     logger.info(f"Model:     {config.model.name}")
     logger.info(f"Context:   {config.model.num_ctx} tokens")
 
-    # JOS ADVANCED-LIPPU ON PÄÄLLÄ
-    if getattr(args, "advanced", False):
-        # Kerätään samat tiedostot kuin ProjectAnalyzer (käyttäen sen sääntöjä)
-        temp_analyzer = ProjectAnalyzer(config, client)
-        files_to_analyze = temp_analyzer._collect_files()
+    # One timestamp for the whole run: findings/guide/specs all share it.
+    run_stamp = _stamp()
+    project_stem = _safe_stem(config.name)
+    is_tty = sys.stdout.isatty()
+
+    # ------------------------------------------------------------------
+    # Advanced per-file specification mode
+    # ------------------------------------------------------------------
+    if args.advanced:
+        analyzer = ProjectAnalyzer(config, client)
+        files_to_analyze = analyzer.collect_files()
 
         if not files_to_analyze:
-            print("No Python files found for advanced specification generation.")
+            print("No analyzable files found for advanced specification generation.")
             return 0
 
         spec_gen = SpecGenerator(config=config, client=client)
-        specs_output_dir = output_dir / f"specs_{config.path.name}_{datetime.now():%Y%m%d_%H%M%S}"
+        specs_output_dir = output_dir / f"specs_{project_stem}_{run_stamp}"
         specs_output_dir.mkdir(parents=True, exist_ok=True)
 
-        print(f"Running advanced per-file technical specification for {len(files_to_analyze)} files...")
+        print(f"Running advanced per-file technical specification "
+              f"for {len(files_to_analyze)} files...")
 
         def progress_cb(current: int, total: int, path: Path) -> None:
-            rel = path.relative_to(config.path).as_posix()
+            try:
+                rel = path.relative_to(config.path).as_posix()
+            except ValueError:
+                rel = path.name
             if len(rel) > 35:
                 rel = "..." + rel[-32:]
-            fraction = current / total
+            fraction = current / total if total else 1.0
             bar_width = 20
             filled = int(bar_width * fraction)
             bar = "█" * filled + "░" * (bar_width - filled)
             msg = f"  [{bar}] {fraction * 100:5.1f}%  ({current}/{total}) {rel}"
-            end_char = "\n" if fraction >= 1.0 else ""
-            print(f"\r\033[K{msg}", end=end_char, flush=True)
+            if is_tty:
+                print(f"\r\033[K{msg}", end="", flush=True)
+                if fraction >= 1.0:
+                    print()
+            else:
+                print(msg, flush=True)
 
         try:
-            specs_dict = spec_gen.generate_project_specs(files_to_analyze, progress_callback=progress_cb)
+            specs_dict = spec_gen.generate_project_specs(
+                files_to_analyze, progress_callback=progress_cb,
+            )
         except KeyboardInterrupt:
             print("\n\ninterrupted by user", file=sys.stderr)
             return 130
+        except LLMError as e:
+            print(f"\nerror: {e}", file=sys.stderr)
+            return 1
         except Exception as e:
             print(f"\nerror: {e}", file=sys.stderr)
             return 1
-        
-        # Tallennetaan tiedostot levylle
+
+        # Write specs to disk. generate_project_specs already returns
+        # only successfully processed files, so specs_dict may be
+        # smaller than files_to_analyze. Count the difference and
+        # surface it to the user.
         for rel_path, markdown_content in specs_dict.items():
+            # Guard against rel_path containing '..' segments, which
+            # would let the write escape specs_output_dir.
+            safe_rel = Path(rel_path)
+            if safe_rel.is_absolute() or ".." in safe_rel.parts:
+                logger.warning(
+                    "Skipping unsafe output path: %s", rel_path,
+                )
+                continue
             target_file = specs_output_dir / f"{rel_path}.md"
             target_file.parent.mkdir(parents=True, exist_ok=True)
             target_file.write_text(markdown_content, encoding="utf-8")
 
+        _save_last_run(config)
+
+        expected = len(files_to_analyze)
+        written = len(specs_dict)
+        missing = expected - written
+
         print()
-        print(f"✓ Advanced specification generation complete")
+        print("✓ Advanced specification generation complete")
         print(f"  Output directory: {specs_output_dir}")
-        print(f"  Files processed:  {len(specs_dict)}")
+        print(f"  Files processed:  {written}")
+        if missing > 0:
+            print(
+                f"{missing} file(s) failed — see warnings above",
+                file=sys.stderr,
+            )
         return 0
 
-    # NORMAALI ANALYYSI
+    # ------------------------------------------------------------------
+    # Normal analysis
+    # ------------------------------------------------------------------
     analyzer = ProjectAnalyzer(config, client)
 
     try:
@@ -224,14 +327,16 @@ def cmd_analyze(args: argparse.Namespace) -> int:
         print(f"\nerror: {e}", file=sys.stderr)
         return 1
 
-    findings_path = output_dir / f"findings_{config.path.name}_{datetime.now():%Y%m%d_%H%M%S}.json"
-    guide_path = output_dir / f"guide_{config.path.name}_{datetime.now():%Y%m%d_%H%M%S}.md"
+    findings_path = output_dir / f"findings_{project_stem}_{run_stamp}.json"
+    guide_path = output_dir / f"guide_{project_stem}_{run_stamp}.md"
 
     analyzer.findings.save(findings_path)
     guide_path.write_text(analyzer.findings.guide, encoding="utf-8")
 
+    _save_last_run(config)
+
     print()
-    print(f"✓ Analysis complete")
+    print("✓ Analysis complete")
     print(f"  Findings: {findings_path}")
     print(f"  Guide:    {guide_path}")
     print(f"  Errors:   {len(analyzer.findings.errors)}")
@@ -264,6 +369,16 @@ def cmd_add(args: argparse.Namespace) -> int:
             return 1
     except FileNotFoundError:
         pass
+    except ValueError as e:
+        # Malformed existing config — overwrite it (the user asked to
+        # add this project, and --force semantics apply).
+        if not args.force:
+            print(
+                f"error: existing config for '{name}' is invalid: {e}\n"
+                f"hint: use --force to overwrite it",
+                file=sys.stderr,
+            )
+            return 1
 
     path = save_project(config)
     print(f"✓ Saved project '{name}'")
@@ -300,6 +415,12 @@ def cmd_show(args: argparse.Namespace) -> int:
     except FileNotFoundError:
         print(f"error: no saved project named '{args.project}'", file=sys.stderr)
         return 1
+    except ValueError as e:
+        print(
+            f"error: saved project '{args.project}' is invalid: {e}",
+            file=sys.stderr,
+        )
+        return 1
 
     print(f"Project: {config.name}")
     print(f"  Path:      {config.path}")