nexus-dev-toolkit 3.0.0__py3-none-any.whl

nexus_cli.py

@@ -0,0 +1,292 @@
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+app = typer.Typer(name="nexus", no_args_is_help=True, help="nexus-dev-toolkit — LLM-agnostic developer workflow toolkit")
+skill_app = typer.Typer(name="skill", no_args_is_help=True, help="Manage skills in .claude/commands/")
+rule_app = typer.Typer(name="rule", no_args_is_help=True, help="Manage rules in knowledge/rules/")
+app.add_typer(skill_app, name="skill")
+app.add_typer(rule_app, name="rule")
+
+console = Console()
+
+# ── Built-in skills shipped with the package ──────────────────────────────────
+
+_SKILLS_SRC = Path(__file__).parent / "tools" / "epav" / "skills"
+
+_BUILTIN_SKILLS = [
+    "scaffold.md",
+    "evaluate.md",
+    "plan.md",
+    "apply.md",
+    "validate.md",
+    "epav.md",
+]
+
+# ── .claude/settings.json ────────────────────────────────────────────────────
+
+_CLAUDE_SETTINGS = {
+    "hooks": {
+        "PostToolUse": [
+            {
+                "matcher": ".*",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "graphify update . --force 2>/dev/null || true"
+                    }
+                ]
+            }
+        ]
+    }
+}
+
+# ── knowledge/ scaffold ───────────────────────────────────────────────────────
+
+_KNOWLEDGE_DIRS = [
+    "knowledge/rules",
+    "knowledge/patterns",
+    "knowledge/prompts/dev",
+    "knowledge/retros",
+]
+
+# ── MCP config ────────────────────────────────────────────────────────────────
+
+_MCP_BLOCK = {
+    "nexus": {
+        "command": "uvx",
+        "args": ["--refresh", "--from", "nexus-dev-toolkit", "nexus-mcp"],
+    }
+}
+
+
+def _init_project(project_dir: Path) -> list[str]:
+    """
+    nexus init — sets up:
+      .claude/commands/     ← built-in skills
+      .claude/settings.json ← PostToolUse graphify hook
+      knowledge/            ← empty scaffold
+    """
+    created = []
+
+    # .claude/commands/ — copy built-in skills
+    commands_dir = project_dir / ".claude" / "commands"
+    commands_dir.mkdir(parents=True, exist_ok=True)
+
+    for skill_name in _BUILTIN_SKILLS:
+        src = _SKILLS_SRC / skill_name
+        dest = commands_dir / skill_name
+        if src.exists() and not dest.exists():
+            shutil.copy2(src, dest)
+            created.append(f".claude/commands/{skill_name}")
+
+    # .claude/settings.json — PostToolUse graphify hook
+    settings_path = project_dir / ".claude" / "settings.json"
+    if not settings_path.exists():
+        settings_path.write_text(json.dumps(_CLAUDE_SETTINGS, indent=2))
+        created.append(".claude/settings.json")
+
+    # knowledge/ scaffold
+    for d in _KNOWLEDGE_DIRS:
+        target = project_dir / d
+        target.mkdir(parents=True, exist_ok=True)
+
+    return created
+
+
+def _write_mcp_config(project_dir: Path) -> str:
+    mcp_path = project_dir / ".mcp.json"
+    existing: dict = {}
+    if mcp_path.exists():
+        try:
+            existing = json.loads(mcp_path.read_text())
+        except Exception:
+            pass
+    existing.setdefault("mcpServers", {}).update(_MCP_BLOCK)
+    mcp_path.write_text(json.dumps(existing, indent=2))
+    return ".mcp.json"
+
+
+# ── Commands ──────────────────────────────────────────────────────────────────
+
+@app.command()
+def init(
+    project_dir: str = typer.Argument(".", help="Project directory to initialize"),
+) -> None:
+    """Initialize .claude/commands/, .claude/settings.json, and knowledge/ in a project."""
+    root = Path(project_dir).resolve()
+    console.print(f"\n  [cyan]▶[/cyan]  Initializing nexus in [bold]{root}[/bold]\n")
+
+    created = _init_project(root)
+    for f in created:
+        console.print(f"  [green]✓[/green]  {f}")
+
+    if not created:
+        console.print("  [yellow]·[/yellow]  Already initialized — nothing to do")
+        return
+
+    mcp = _write_mcp_config(root)
+    console.print(f"  [green]✓[/green]  {mcp}")
+
+    console.print(f"\n  [bold green]Done.[/bold green] Open [bold]{root}[/bold] in Claude Code and type [cyan]/scaffold[/cyan]\n")
+
+
+@app.command()
+def update() -> None:
+    """Update nexus-dev-toolkit to the latest version."""
+    console.print("\n  [cyan]▶[/cyan]  Updating nexus-dev-toolkit…\n")
+    if shutil.which("uv"):
+        subprocess.run(["uv", "tool", "upgrade", "nexus-dev-toolkit"])
+    else:
+        subprocess.run([sys.executable, "-m", "pip", "install", "--upgrade", "nexus-dev-toolkit"])
+    console.print("\n  [green]✓[/green]  Done.\n")
+
+
+# ── skill subcommands ─────────────────────────────────────────────────────────
+
+_SKILL_TEMPLATE = """\
+# /{name}
+
+**{name}** — describe what this skill does.
+
+## When to use
+
+Describe the trigger or context.
+
+## Steps
+
+### 1 — First step
+
+What to do.
+
+### 2 — Second step
+
+What to do next.
+
+### 3 — Output
+
+What the AI should produce when done.
+"""
+
+
+@skill_app.command("add")
+def skill_add(
+    name: str = typer.Argument(..., help="Skill name (e.g. 'code-review')"),
+    project_dir: str = typer.Option(".", "--dir", "-d"),
+) -> None:
+    """Create a new skill in .claude/commands/."""
+    root = Path(project_dir).resolve()
+    dest = root / ".claude" / "commands" / f"{name}.md"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    if dest.exists():
+        console.print(f"  [yellow]·[/yellow]  .claude/commands/{name}.md already exists")
+        return
+
+    dest.write_text(_SKILL_TEMPLATE.format(name=name), encoding="utf-8")
+    console.print(f"  [green]✓[/green]  Created .claude/commands/{name}.md")
+    console.print(f"  [dim]Edit it and type [cyan]/{name}[/cyan] in Claude Code.[/dim]")
+
+
+@skill_app.command("list")
+def skill_list(
+    project_dir: str = typer.Option(".", "--dir", "-d"),
+) -> None:
+    """List all skills in .claude/commands/."""
+    root = Path(project_dir).resolve()
+    commands_dir = root / ".claude" / "commands"
+
+    if not commands_dir.exists():
+        console.print("  [yellow]·[/yellow]  No .claude/commands/ found. Run [cyan]nexus init[/cyan] first.")
+        return
+
+    skills = sorted(commands_dir.glob("*.md"))
+    if not skills:
+        console.print("  [yellow]·[/yellow]  No skills yet. Run [cyan]nexus skill add <name>[/cyan]")
+        return
+
+    table = Table(show_header=True, header_style="dim")
+    table.add_column("Skill", style="cyan")
+    table.add_column("Source")
+
+    builtins = set(_BUILTIN_SKILLS)
+    for s in skills:
+        source = "built-in" if s.name in builtins else "custom"
+        table.add_row(f"/{s.stem}", source)
+
+    console.print(table)
+
+
+# ── rule subcommands ──────────────────────────────────────────────────────────
+
+_RULE_TEMPLATE = """\
+# {name}
+
+_Project rule — read by AI tools via AGENTS.md._
+
+## Rules
+
+- Rule one
+- Rule two
+- Rule three
+
+## Rationale
+
+Why these rules exist.
+"""
+
+
+@rule_app.command("add")
+def rule_add(
+    name: str = typer.Argument(..., help="Rule name (e.g. 'api-standards')"),
+    project_dir: str = typer.Option(".", "--dir", "-d"),
+) -> None:
+    """Create a new rule in knowledge/rules/."""
+    root = Path(project_dir).resolve()
+    dest = root / "knowledge" / "rules" / f"{name}.md"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    if dest.exists():
+        console.print(f"  [yellow]·[/yellow]  knowledge/rules/{name}.md already exists")
+        return
+
+    dest.write_text(_RULE_TEMPLATE.format(name=name), encoding="utf-8")
+    console.print(f"  [green]✓[/green]  Created knowledge/rules/{name}.md")
+
+
+@rule_app.command("list")
+def rule_list(
+    project_dir: str = typer.Option(".", "--dir", "-d"),
+) -> None:
+    """List all rules in knowledge/rules/."""
+    root = Path(project_dir).resolve()
+    rules_dir = root / "knowledge" / "rules"
+
+    if not rules_dir.exists():
+        console.print("  [yellow]·[/yellow]  No knowledge/rules/ found. Run [cyan]nexus init[/cyan] first.")
+        return
+
+    rules = sorted(rules_dir.glob("*.md"))
+    if not rules:
+        console.print("  [yellow]·[/yellow]  No rules yet. Run [cyan]nexus rule add <name>[/cyan]")
+        return
+
+    table = Table(show_header=True, header_style="dim")
+    table.add_column("Rule", style="cyan")
+    for r in rules:
+        table.add_row(r.stem)
+    console.print(table)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

nexus_dev_toolkit-3.0.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: nexus-dev-toolkit
+Version: 3.0.0
+Summary: LLM-agnostic developer workflow toolkit — Day 0 scaffold + Day 1 EPAV
+Author-email: Ronald dela Cruz <rcdelacruz@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://nexus.coderstudio.co
+Project-URL: Repository, https://github.com/rcdelacruz/nexus-dev-toolkit
+Project-URL: Issues, https://github.com/rcdelacruz/nexus-dev-toolkit/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Dynamic: license-file
+
+# nexus-dev-toolkit
+
+[![PyPI version](https://img.shields.io/pypi/v/nexus-dev-toolkit)](https://pypi.org/project/nexus-dev-toolkit/)
+[![Python](https://img.shields.io/pypi/pyversions/nexus-dev-toolkit)](https://pypi.org/project/nexus-dev-toolkit/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Developer workflow toolkit for AI-assisted development. Gives any team a structured Day 0 scaffold and repeatable Day 1 feature cycle via the EPAV methodology.
+
+---
+
+## Why
+
+Ad-hoc AI prompting doesn't scale. Every dev prompts differently, context drifts, and nobody knows what the AI was told last sprint.
+
+`nexus-dev-toolkit` gives your team a single workflow:
+
+- **Day 0** — scaffold the project once, production-grade, zero credentials needed
+- **Day 1** — every feature follows the same four steps: evaluate → plan → apply → validate
+
+Every skill, every rule, every pattern lives in the project repo — versioned, shared, and enforced.
+
+---
+
+## The Workflow
+
+### Day 0 — `/scaffold` (once per project)
+
+```
+nexus init <project-dir>
+```
+
+Sets up `.claude/commands/`, `.claude/settings.json`, and `knowledge/`. Then in Claude Code:
+
+```
+/scaffold
+```
+
+EVALUATE → PLAN → APPLY → VALIDATE. Produces a production-grade project: correct stack from your arch doc, mock auth, mock data, design system, AGENTS.md — all from your architecture document. Runs with `npm install && npm run dev` (or equivalent) from commit one.
+
+### Day 1 — EPAV (every feature, every sprint)
+
+```
+/evaluate   →   /plan   →   /apply   →   /validate
+```
+
+Each step is a built-in skill in `.claude/commands/`. Every task starts with a row from the dev tasks CSV. Every task ends with acceptance criteria verified.
+
+---
+
+## Install
+
+**Requirements:** Python 3.10+, `uv` (recommended) or `pip`
+
+```bash
+# Recommended
+uv tool install nexus-dev-toolkit
+
+# Or via pip
+pip install nexus-dev-toolkit
+```
+
+---
+
+## Quick Start
+
+```bash
+cd my-project
+nexus init .
+```
+
+Then open the project in Claude Code and type `/scaffold`.
+
+---
+
+## Commands
+
+```bash
+nexus init .                 # set up .claude/commands/ + knowledge/ + .mcp.json
+nexus skill add code-review  # create a custom skill in .claude/commands/
+nexus skill list             # list all skills
+nexus rule add api-standards # create a rule in knowledge/rules/
+nexus rule list              # list all rules
+nexus update                 # update to latest version
+```
+
+---
+
+## What `nexus init` Creates
+
+```
+.claude/
+├── commands/
+│   ├── scaffold.md    ← /scaffold  — Day 0 one-time setup
+│   ├── evaluate.md    ← /evaluate  — orient on a task
+│   ├── plan.md        ← /plan      — blueprint, no code
+│   ├── apply.md       ← /apply     — implement the plan
+│   ├── validate.md    ← /validate  — verify acceptance criteria
+│   └── epav.md        ← /epav      — full cycle guide
+└── settings.json      ← PostToolUse hook: graphify auto-updates after every file edit
+knowledge/
+├── rules/             ← coding standards, arch decisions
+├── patterns/          ← reusable implementation patterns
+├── prompts/dev/       ← task prompt templates
+└── retros/            ← retrospective notes
+.mcp.json              ← MCP server config
+```
+
+---
+
+## MCP Server
+
+```json
+{
+  "mcpServers": {
+    "nexus": {
+      "command": "uvx",
+      "args": ["--refresh", "--from", "nexus-dev-toolkit", "nexus-mcp"]
+    }
+  }
+}
+```
+
+`nexus init` writes `.mcp.json` automatically.
+
+### MCP Tools
+
+| Tool | Purpose |
+|---|---|
+| `ingest_architecture_doc` | Load arch doc → `knowledge/rules/arch-summary.md` |
+| `load_task` | Load a CSV task row into context |
+| `generate_project_rules` | Generate `AGENTS.md` from arch doc |
+| `resolve_package_versions` | Resolve exact package versions via real package manager |
+
+---
+
+## Custom Skills
+
+```bash
+nexus skill add my-code-review
+# Edit .claude/commands/my-code-review.md
+# Type /my-code-review in Claude Code
+```
+
+Custom skills live alongside built-in skills in `.claude/commands/` — versioned in your repo, shared across the team.
+
+---
+
+## License
+
+[MIT](LICENSE)

nexus_dev_toolkit-3.0.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+nexus_cli.py,sha256=Z8bwSC5T9-_uaB273g24-TZjit_lxyv46T9-6zB-wnE,9118
+nexus_server.py,sha256=XSo_2Azq28sqL8bKL4ahx7hsgTuABgwmiZBHIs_EQtM,278
+nexus_dev_toolkit-3.0.0.dist-info/licenses/LICENSE,sha256=IebhcEWRJRzVU5aZPAAN1-xa36NeQtJ3lnA3KF-dKnA,1073
+tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tools/epav/__init__.py,sha256=U5_ZOSDCyS7l688craVbj13_aD86pYOHooLo-YGoeew,559
+tools/epav/arch_ingest.py,sha256=EqoEqcfLg76_ISU7Jlpdk9xpl5YfEofXOn7NrNpESXM,4810
+tools/epav/package_resolver.py,sha256=DMpXR-wXJbWc5eTbCUyUD-ujRvn8ZJKRoJUoQRgBX_Y,9508
+tools/epav/project_rules.py,sha256=glz6hoEkOXWtPcrotphcT5g0wjXATcyS_VYPgCo0Qas,6958
+tools/epav/task_loader.py,sha256=t7WeYL3LGF2t8mijj_mpl0iiglWK6T4cRFjbWv39Wm4,5243
+tools/epav/skills/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tools/epav/skills/apply.md,sha256=mQEAQwT0Bqkf9CVIAyLvI7nctGmbI6zn0szqQYOzvy8,1115
+tools/epav/skills/epav.md,sha256=Z-Uy3Ej-V-8OWtaWFKygLI1wO-EGQlWZOB8p-jz9t_Y,1317
+tools/epav/skills/evaluate.md,sha256=KMQbKQ1lVJDtl9w12Al4v-gC7LlnQPNkJ8spyvidP1c,1400
+tools/epav/skills/plan.md,sha256=bj2IGu8FyfaJp-WojzsM3aQuRauiE8cGPbZkfX1EWLU,1046
+tools/epav/skills/scaffold.md,sha256=xAhxWfhYKIdvLrhEl4dU8BYp9P6q9q0g0ifmM7YXJuo,10952
+tools/epav/skills/validate.md,sha256=qLYuQgGwKT1bWFOlXSmsAounvkfPrfVOrVo5Pk0fvRg,1411
+nexus_dev_toolkit-3.0.0.dist-info/METADATA,sha256=uf5PnsuSij31wLmdqvb0LfM1lJhaptHENx8PvG9aNhE,4943
+nexus_dev_toolkit-3.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+nexus_dev_toolkit-3.0.0.dist-info/entry_points.txt,sha256=X6brRRXNnOreQFKMXeF0mbTVmpzWHX44VGOrVeGL6-Q,71
+nexus_dev_toolkit-3.0.0.dist-info/top_level.txt,sha256=_3H722hZfNwMcAzexQoFrJ-I-tceGD42Zxe1re8MMSc,29
+nexus_dev_toolkit-3.0.0.dist-info/RECORD,,

nexus_dev_toolkit-3.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nexus_dev_toolkit-3.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+nexus = nexus_cli:main
+nexus-mcp = nexus_server:main

nexus_dev_toolkit-3.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ronald dela Cruz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nexus_dev_toolkit-3.0.0.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+nexus_cli
+nexus_server
+tools

nexus_server.py

@@ -0,0 +1,16 @@
+import logging
+from mcp.server.fastmcp import FastMCP
+from tools.epav import register_epav_tools
+
+logging.basicConfig(level=logging.WARNING)
+
+mcp = FastMCP("nexus-dev-toolkit")
+register_epav_tools(mcp)
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

tools/epav/__init__.py

@@ -0,0 +1,14 @@
+from mcp.server.fastmcp import FastMCP
+
+from tools.epav.arch_ingest import register_arch_ingest_tool
+from tools.epav.task_loader import register_task_loader_tool
+from tools.epav.project_rules import register_project_rules_tool
+from tools.epav.package_resolver import register_package_resolver_tool
+
+
+def register_epav_tools(mcp: FastMCP) -> None:
+    """Register Day 0 + Day 1 EPAV tools onto the MCP server."""
+    register_arch_ingest_tool(mcp)
+    register_task_loader_tool(mcp)
+    register_project_rules_tool(mcp)
+    register_package_resolver_tool(mcp)

tools/epav/arch_ingest.py

@@ -0,0 +1,124 @@
+import json
+import logging
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+
+logger = logging.getLogger(__name__)
+
+_ARCH_SECTIONS = [
+    "stack", "tech stack", "technology stack",
+    "data model", "schema", "database",
+    "auth", "authentication", "authorization",
+    "error", "error handling", "error format",
+    "security", "cors", "headers",
+    "adr", "architecture decision",
+    "api", "conventions", "standards",
+    "middleware", "infrastructure",
+]
+
+
+def _extract_sections(text: str) -> dict:
+    """Pull labelled sections from markdown text by heading keywords."""
+    sections: dict[str, list[str]] = {}
+    current_key = "preamble"
+    current_lines: list[str] = []
+
+    for line in text.splitlines():
+        stripped = line.lstrip("#").strip().lower()
+        matched = next((k for k in _ARCH_SECTIONS if k in stripped), None)
+        if line.startswith("#") and matched:
+            if current_lines:
+                sections[current_key] = current_lines
+            current_key = stripped
+            current_lines = [line]
+        else:
+            current_lines.append(line)
+
+    if current_lines:
+        sections[current_key] = current_lines
+
+    return {k: "\n".join(v).strip() for k, v in sections.items() if v}
+
+
+def register_arch_ingest_tool(mcp: FastMCP) -> None:
+
+    @mcp.tool()
+    async def ingest_architecture_doc(
+        doc_path: str = "",
+        save_summary: bool = True,
+    ) -> str:
+        """
+        Ingest an architecture document and extract key decisions for the EPAV workflow.
+
+        Reads a markdown architecture doc (or scans docs/arch-docs/ if no path given),
+        extracts stack decisions, data model, auth strategy, error format, security rules,
+        and ADR list. Optionally writes a summary to knowledge/rules/arch-summary.md.
+
+        Args:
+            doc_path: Path to the architecture doc (.md) or a directory containing
+                      arch docs. If empty, looks for docs/arch-docs/ in the project root.
+            save_summary: If True, writes extracted summary to
+                          knowledge/rules/arch-summary.md (creates dirs if needed).
+
+        Returns:
+            JSON with extracted architecture sections and file paths written.
+        """
+        try:
+            # Resolve the source path
+            source = Path(doc_path) if doc_path else Path("docs/arch-docs")
+
+            if not source.exists():
+                return json.dumps({
+                    "error": f"Path not found: {source}. "
+                             "Provide doc_path or create docs/arch-docs/ with your architecture doc."
+                })
+
+            # Collect markdown files
+            if source.is_file():
+                md_files = [source]
+            else:
+                md_files = sorted(source.rglob("*.md")) + sorted(source.rglob("*.txt"))
+
+            if not md_files:
+                return json.dumps({"error": f"No markdown files found in {source}"})
+
+            # Extract sections from all files
+            all_sections: dict[str, str] = {}
+            files_read = []
+            for f in md_files:
+                try:
+                    text = f.read_text(encoding="utf-8")
+                    sections = _extract_sections(text)
+                    all_sections.update(sections)
+                    files_read.append(str(f))
+                except Exception as e:
+                    logger.warning("Could not read %s: %s", f, e)
+
+            if not all_sections:
+                return json.dumps({
+                    "error": "No recognisable architecture sections found. "
+                             "Check that headings use standard terms (stack, auth, data model, etc.)."
+                })
+
+            files_written = []
+            if save_summary:
+                summary_path = Path("knowledge/rules/arch-summary.md")
+                summary_path.parent.mkdir(parents=True, exist_ok=True)
+                lines = ["# Architecture Summary\n", "_Auto-generated by ingest_architecture_doc_\n"]
+                for section, content in all_sections.items():
+                    lines.append(f"\n## {section.title()}\n\n{content}\n")
+                summary_path.write_text("\n".join(lines), encoding="utf-8")
+                files_written.append(str(summary_path))
+
+            return json.dumps({
+                "files_read": files_read,
+                "files_written": files_written,
+                "sections_extracted": list(all_sections.keys()),
+                "summary": {k: v[:300] + "…" if len(v) > 300 else v
+                            for k, v in all_sections.items()},
+            }, indent=2)
+
+        except Exception as e:
+            logger.exception("Unexpected error in ingest_architecture_doc")
+            return json.dumps({"error": f"Unexpected error: {e}"})