docs: comprehensive update for all session changes

Upgrader: init credit tracking on upgrade (joins init + import)

CHANGELOG: full unreleased section covering credits (#50/#51), architect
(#49), self-update, multi-language, dynamic versioning, templates
(#39/#40/#43), import quality (#46/#47/#48), all bug fixes

README: updated command table (40+ commands), added architect/self-update/credits

REQUIREMENTS.md: 20 new requirements across 5 sections:
- REQ-CRD-001..009 (credit tracking)
- REQ-ARC-001..004 (architecture generation)
- REQ-SLF-001..003 (self-update)
- REQ-TPL-005..008 (templates)

TEST_SPEC.md: added TEST-SBX-013/014 (import with existing docs)

RTD commands.md: added architect, self-update, credits command docs

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: tbitcs

CHANGELOG.md

@@ -8,20 +8,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- **Dynamic versioning**: `__version__` now reads from `importlib.metadata` at runtime instead of hardcoded strings. Docs use `{{ version }}` placeholders resolved by MkDocs hook. Tests are version-agnostic.
-- **Multi-language detection**: importer now detects and reports all significant languages (primary + secondary). Architecture, AGENTS.md, and CLI display show the full language mix.
-- **`specsmith self-update`** command: auto-detects channel (stable/dev), supports `--channel` override and `--version` pinning.
-- **Dev-release workflow for managed projects** (#35): `specsmith init` with gitflow + GitHub + Python now generates `.github/workflows/dev-release.yml`.
-- **No-hardcoded-versions rule** (H10): governance template and WARP rule enforce `pyproject.toml` as single version source of truth.
-- **Separate PyPI badges**: README shows both stable (blue) and dev (orange) version badges.
+- **AI credit tracking** (#50): `specsmith credits` subcommand group — record, summary, report, analyze, budget. Tracks tokens/cost per session, model, provider, and task. JSON storage at `.specsmith/credits.json`.
+- **Credit spend analysis** (#51): `specsmith credits analyze` detects model inefficiency, token waste, governance bloat, cost trends. Generates optimization recommendations with estimated savings.
+- **Credit budget/watermarks**: `specsmith credits budget --cap 50 --watermarks 5,10,25,50`. Monthly caps, alert thresholds, watermark notifications. Filed #52 for hard-cap enforcement.
+- **Auto-init credit tracking**: `init`, `import`, and `upgrade` all create `.specsmith/credit-budget.json` with unlimited default budget. `.specsmith/` gitignored.
+- **`specsmith architect`** (#49): interactive architecture generation — scans project, interviews user about components/data flow/deployment, generates rich `docs/architecture.md`.
+- **`specsmith self-update`**: auto-detects channel (stable/dev), supports `--channel` override and `--version` pinning.
+- **Multi-language detection**: importer detects and reports all significant languages (primary + secondary).
+- **Dynamic versioning**: `__version__` reads from `importlib.metadata`. Docs use `{{ version }}` hook. Tests are version-agnostic.
+- **Dev-release workflow for managed projects** (#35): gitflow + GitHub + Python generates `.github/workflows/dev-release.yml`.
+- **Type-specific templates**: .gitattributes (#39) for 15 language types, .gitignore (#40) expanded for all 30 types, .editorconfig (#43) with per-language indent settings.
+- **Yocto/bitbake/devicetree/markdown**: `.bbclass`, `.inc`, `.dts`, `.dtsi` in language detection; `kas.yml` build system; enhanced CI metadata.
+- **No-hardcoded-versions rule** (H10): governance template and WARP rule.
+- **Agent credit instructions**: Warp and Claude adapters include credit recording commands.
+- **Session-end credit summary**: `session-end` shows total spend and budget alerts.
 
 ### Fixed
-- **Import with large AGENTS.md** (#46): extraction now uses broader keyword matching, unmatched sections go to rules.md, oversized AGENTS.md is backed up and replaced with a hub.
+- **Import with large AGENTS.md** (#46): broader keyword extraction, diff marker stripping, paragraph dedup, existing doc detection.
+- **UnboundLocalError on import** with existing docs: scoping fix for REQUIREMENTS/TEST_SPEC/architecture skip logic.
+- **Audit false positive**: architecture docs found in subdirectories (e.g., `docs/architecture/DESIGN.md`).
+- **`audit --fix`** now generates missing recommended files (architecture.md from scan, REQUIREMENTS.md, TEST_SPEC.md stubs).
+- **Topic-aware section classification** (#47): body content keywords route sections to correct governance files.
+- **Type-specific audit thresholds** (#48): FPGA/embedded get higher limits (rules=1000, verification=600).
 
 ### Changed
-- RTD default version set to `stable`, default branch set to `develop` (`latest` now builds from develop).
+- RTD default version set to `stable`, default branch set to `develop`.
 - Docs version references use dynamic `{{ version }}` instead of hardcoded strings.
 - `init.py.j2` template for managed projects uses `importlib.metadata` pattern.
+- Governance file size thresholds raised globally (rules=800, verification=400).
+- Yocto toolset: added `testimage`, `yocto-check-layer` compliance.
 
 ## [0.1.3] - 2026-04-01
 

README.md

@@ -56,20 +56,23 @@ specsmith doctor --project-dir ./my-project        # Tool check
 
 Each type gets: tool-aware CI (correct lint/test/security/build tools), domain-specific directory structure, governance rules in AGENTS.md, and pre-populated requirements and test stubs.
 
-## 30+ CLI Commands
+## 40+ CLI Commands
 
 | Command | Purpose |
 |---------|---------|
 | `init` | Scaffold a new governed project |
 | `import` | Adopt an existing project (merge mode) |
 | `audit` | Drift detection and health checks (`--fix` to auto-repair) |
+| `architect` | Interactive architecture generation |
 | `validate` | Governance file consistency checks |
 | `compress` | Archive old ledger entries |
 | `upgrade` | Update governance to new spec version |
 | `status` | CI/PR/alert status from VCS platform |
 | `diff` | Compare governance against templates |
 | `export` | Compliance report with REQ↔TEST coverage |
 | `doctor` | Check if verification tools are installed |
+| `self-update` | Update specsmith (channel-aware) |
+| `credits` | AI credit tracking, analysis, and budgets |
 
 ## 7 Agent Integrations
 

docs/REQUIREMENTS.md

@@ -150,6 +150,38 @@
 - **REQ-WFL-009**: specsmith commit --auto-push option to commit and push in one step
 - **REQ-WFL-010**: specsmith session-end provides checklist (unpushed commits, open TODOs, dirty files)
 
+## Credit Tracking
+
+- **REQ-CRD-001**: `specsmith credits record` stores token usage entry with model, provider, tokens, task, and estimated cost
+- **REQ-CRD-002**: `specsmith credits summary` shows aggregate spend by model, provider, and task
+- **REQ-CRD-003**: `specsmith credits report` generates markdown credit report
+- **REQ-CRD-004**: `specsmith credits analyze` detects model inefficiency, token waste, and cost trends
+- **REQ-CRD-005**: `specsmith credits budget` configures monthly cap, alert threshold, and watermark levels
+- **REQ-CRD-006**: Credit tracking auto-initialized on init, import, and upgrade with unlimited default
+- **REQ-CRD-007**: `.specsmith/` directory gitignored by default in generated projects
+- **REQ-CRD-008**: Session-end checklist includes credit summary and budget alerts
+- **REQ-CRD-009**: Agent adapters (Warp, Claude) include credit recording instructions
+
+## Architecture Generation
+
+- **REQ-ARC-001**: `specsmith architect` scans project for modules, languages, dependencies, git history
+- **REQ-ARC-002**: `specsmith architect` runs interactive interview for components, data flow, deployment
+- **REQ-ARC-003**: `specsmith architect --non-interactive` auto-generates without prompts
+- **REQ-ARC-004**: `audit --fix` generates architecture.md from project scan when missing
+
+## Self-Update
+
+- **REQ-SLF-001**: `specsmith self-update` auto-detects channel (stable/dev) from installed version
+- **REQ-SLF-002**: `specsmith self-update --channel dev` forces dev channel
+- **REQ-SLF-003**: `specsmith self-update --version X.Y.Z` pins to specific version
+
+## Templates
+
+- **REQ-TPL-005**: .gitattributes template includes type-specific patterns for all 30 project types
+- **REQ-TPL-006**: .gitignore template includes type-specific patterns for all 30 project types
+- **REQ-TPL-007**: .editorconfig template includes type-specific indent/EOL settings
+- **REQ-TPL-008**: Yocto/bitbake language detection includes .bbclass, .inc, .dts, .dtsi
+
 ## Cross-Platform
 
 - **REQ-XPL-001**: All CLI commands work on Windows, Linux, and macOS

docs/TEST_SPEC.md

@@ -173,6 +173,13 @@
 - **TEST-SBX-007**: Auditor tool verification on scaffolded project
   Covers: REQ-AUD-007, REQ-AUD-008
 
+### Sandbox — Import with Existing Docs
+
+- **TEST-SBX-013**: Import preserves existing REQUIREMENTS.md, TEST_SPEC.md, architecture docs
+  Covers: REQ-IMP-008
+- **TEST-SBX-014**: Import with --force overwrites existing docs
+  Covers: REQ-IMP-008
+
 ### Sandbox — Non-Python Types
 
 - **TEST-SBX-008**: Patent application scaffold with domain directories, requirements, tests, tools

docs/site/commands.md

@@ -1,6 +1,6 @@
 # CLI Commands
 
-specsmith has 11 commands. Every command that operates on a project accepts `--project-dir PATH` (default: current directory).
+specsmith has 40+ commands. Every command that operates on a project accepts `--project-dir PATH` (default: current directory).
 
 ## `specsmith init`
 
@@ -157,6 +157,57 @@ Reads scaffold.yml, looks up the ToolSet for the project type, and checks if eac
 
 See [Doctor](doctor.md) for details.
 
+## `specsmith architect`
+
+Generate or enrich architecture documentation by scanning the project and interviewing you.
+
+```bash
+specsmith architect --project-dir ./my-project
+specsmith architect --project-dir ./my-project --non-interactive
+```
+
+**What it does:** Scans for modules, languages, dependencies, git history, and existing architecture docs. In interactive mode, prompts for component names, purposes, interfaces, data flow, and deployment notes. Generates a rich `docs/architecture.md`.
+
+**Options:**
+
+- `--non-interactive` — Skip prompts, auto-generate from scan data only.
+
+## `specsmith self-update`
+
+Update specsmith itself.
+
+```bash
+specsmith self-update                       # Auto-detect channel
+specsmith self-update --channel dev          # Force dev channel
+specsmith self-update --version 0.1.3        # Pin specific version
+```
+
+Auto-detects whether you're on stable or dev and upgrades accordingly.
+
+## `specsmith credits`
+
+AI credit/token spend tracking and analysis.
+
+```bash
+specsmith credits summary                                # Spend overview
+specsmith credits summary --month 2026-04                # Monthly view
+specsmith credits record --model claude-sonnet \          # Record usage
+  --provider anthropic --tokens-in 5000 --tokens-out 2000 --task "import"
+specsmith credits report --output credits-report.md      # Markdown report
+specsmith credits analyze                                # Optimization insights
+specsmith credits budget --cap 50 --alert-pct 80         # Set budget
+```
+
+**Subcommands:**
+
+- `summary` — Aggregate spend by model, provider, task. Shows budget alerts.
+- `record` — Log a credit usage entry (model, provider, tokens, task, cost).
+- `report` — Generate markdown credit report.
+- `analyze` — Detect model inefficiency, token waste, cost trends. Recommendations.
+- `budget` — View/set monthly cap, alert threshold, watermark levels.
+
+Credit data stored locally at `.specsmith/credits.json` (gitignored).
+
 ## `specsmith --version`
 
 ```bash

src/specsmith/upgrader.py

@@ -110,6 +110,14 @@ def run_upgrade(
         yaml.dump(raw, f, default_flow_style=False, sort_keys=False)
     result.updated_files.append("scaffold.yml")
 
+    # Initialize credit tracking if not present
+    specsmith_dir = root / ".specsmith"
+    if not specsmith_dir.exists():
+        from specsmith.credits import CreditBudget, save_budget
+
+        save_budget(root, CreditBudget())
+        result.updated_files.append(".specsmith/credit-budget.json")
+
     result.message = (
         f"Upgraded from {old_version} to {new_version}. "
         f"{len(result.updated_files)} files updated, {len(result.skipped_files)} skipped."