feat: auto-init credit tracking, agent credit instructions, session-end credits

Credit tracking is now automatic:
- specsmith init creates .specsmith/credit-budget.json (unlimited default)
- specsmith import creates .specsmith/ on first import
- .specsmith/ added to .gitignore template (credit data is local-only)
- .specsmith/ excluded from importer file scan

Agent integrations include credit instructions:
- Warp SKILL.md: credit recording command + budget check
- Claude CLAUDE.md: credit recording with anthropic provider
- context-budget.md.j2 template: credit tracking section for all projects

Session-end checklist includes credit summary:
- Shows total spend and session count
- Surfaces budget alerts (watermark, cap warnings)

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

Author: tbitcs

src/specsmith/importer.py

@@ -168,6 +168,7 @@ def detect_project(root: Path) -> DetectionResult:
         ".ruff_cache",
         ".mypy_cache",
         ".work",
+        ".specsmith",
         "build",
         "dist",
         "target",
@@ -1117,6 +1118,14 @@ def _write(rel_path: str, content: str) -> None:
             agents_path.write_text(hub, encoding="utf-8")
             created.append(agents_path)
 
+    # Initialize credit tracking with unlimited budget
+    specsmith_dir = target / ".specsmith"
+    if not specsmith_dir.exists():
+        from specsmith.credits import CreditBudget, save_budget
+
+        save_budget(target, CreditBudget())  # unlimited by default
+        created.append(target / ".specsmith" / "credit-budget.json")
+
     # --- CI config (merge: only create if no CI detected) ---
     if not result.existing_ci and result.vcs_platform:
         try:

src/specsmith/integrations/claude_code.py

@@ -78,4 +78,10 @@ def _render(self, config: ProjectConfig) -> str:
 When user says `pr`: run `specsmith pr --project-dir .`
 When user says `audit`: run `specsmith audit --project-dir .`
 When user says `session-end`: run `specsmith session-end --project-dir .`
+
+## Credit Tracking
+At session end, record token usage:
+`specsmith credits record --model <model> --provider anthropic \
+  --tokens-in <N> --tokens-out <N> --task "<desc>"`
+Check budget: `specsmith credits summary`
 """

src/specsmith/integrations/warp.py

@@ -84,10 +84,19 @@ def _render_skill(self, config: ProjectConfig) -> str:
 ## Verification
 Before marking any task complete, run: {verify_line}
 
+## Credit Tracking
+After completing tasks, record token usage:
+```
+specsmith credits record --model <model> --provider <provider> \
+  --tokens-in <N> --tokens-out <N> --task "<desc>"
+```
+Check budget: `specsmith credits summary`
+
 ## Rules
 - Proposals before changes (no exceptions)
 - Verify before recording completion
 - Use execution shims (`scripts/exec.cmd` / `scripts/exec.sh`) for external commands
 - Keep AGENTS.md under 200 lines
 - Record every session in the ledger
+- Record credit usage at session end
 """

src/specsmith/scaffolder.py

@@ -80,6 +80,12 @@ def scaffold_project(config: ProjectConfig, target: Path) -> list[Path]:
         except ValueError:
             pass  # Unknown platform — skip silently
 
+    # Initialize credit tracking with unlimited budget
+    from specsmith.credits import CreditBudget, save_budget
+
+    save_budget(target, CreditBudget())  # unlimited by default
+    created.append(target / ".specsmith" / "credit-budget.json")
+
     # Git init
     if config.git_init:
         subprocess.run(  # noqa: S603

src/specsmith/session.py

@@ -127,4 +127,27 @@ def run_session_end(root: Path) -> SessionReport:
             SessionCheck(name="audit", status="warn", message="Could not run audit")
         )
 
+    # Credit spend summary for this session
+    try:
+        from specsmith.credits import get_summary
+
+        cs = get_summary(root)
+        if cs.entry_count > 0:
+            report.checks.append(
+                SessionCheck(
+                    name="credits",
+                    status="ok",
+                    message=(
+                        f"Credits: ${cs.total_cost_usd:.4f} total, "
+                        f"{cs.session_count} session(s)"
+                    ),
+                )
+            )
+            for alert in cs.alerts:
+                report.checks.append(
+                    SessionCheck(name="credit-alert", status="warn", message=alert)
+                )
+    except Exception:  # noqa: BLE001
+        pass  # Credits not configured — skip silently
+
     return report

src/specsmith/templates/gitignore.j2

@@ -36,6 +36,9 @@ htmlcov/
 # Build artifacts
 .work/
 *.log
+
+# specsmith local data (credits, config)
+.specsmith/
 {% if project.type.value in ('cli-rust', 'library-rust') %}
 
 # Rust

src/specsmith/templates/governance/context-budget.md.j2

@@ -48,3 +48,14 @@ If a cheaper check fails, fix that before running more expensive checks.
 - **low** — docs-only, single-file edits, small scaffolds
 - **medium** — multi-file implementation, routine refactors, standard test runs
 - **high** — architecture changes, large builds, broad audits
+
+## Credit tracking
+
+This project tracks AI credit spend automatically. At the end of each session:
+
+1. Record usage: `specsmith credits record --model <model> --provider <provider> --tokens-in <N> --tokens-out <N> --task "<description>"`
+2. Check budget: `specsmith credits summary`
+3. If budget alerts appear, review with: `specsmith credits analyze`
+
+Budget configuration: `specsmith credits budget --cap <USD> --alert-pct 80`
+Credit data stored in `.specsmith/credits.json` (gitignored).