caudate-cli 0.1.0__py3-none-any.whl

main.py

@@ -0,0 +1,1889 @@
+"""Cognos — A Minimal Cognitive Architecture for AGI Research.
+
+Main entry point with CLI interface.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import sys
+from pathlib import Path
+
+# Force the `transformers` library to skip its TensorFlow integration.
+# A broken/partial TF install (DType serialization conflict on TF 2.21+)
+# can poison the import chain via transformers' lazy loader. We never
+# use TF anywhere in Cognos, so this is purely defensive. Set BEFORE
+# any module that may import transformers.
+os.environ.setdefault("USE_TF", "0")
+os.environ.setdefault("TRANSFORMERS_NO_ADVISORY_WARNINGS", "1")
+
+# Add project root to path
+sys.path.insert(0, str(Path(__file__).parent))
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+
+from core.agent import CognosAgent
+from config import LLM_MODEL
+
+console = Console()
+
+
+def setup_logging(verbose: bool = False) -> None:
+    """Configure logging.
+
+    The file handler writes to `./logs/cognos.log` when run from a repo
+    checkout (the historical layout), otherwise falls back to
+    `~/.cognos/logs/cognos.log` so a pip-installed `cognos` works from
+    any CWD. Missing parent directories are created.
+    """
+    import os
+    level = logging.DEBUG if verbose else logging.INFO
+    repo_logs = os.path.join(os.getcwd(), "logs")
+    if os.path.isdir(repo_logs):
+        log_path = os.path.join(repo_logs, "cognos.log")
+    else:
+        user_logs = os.path.join(os.path.expanduser("~"), ".cognos", "logs")
+        os.makedirs(user_logs, exist_ok=True)
+        log_path = os.path.join(user_logs, "cognos.log")
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s [%(name)s] %(levelname)s: %(message)s",
+        handlers=[
+            logging.FileHandler(log_path),
+            logging.StreamHandler() if verbose else logging.NullHandler(),
+        ],
+    )
+
+
+@click.group(invoke_without_command=True)
+@click.option("--model", default=None, help="LLM model")
+@click.option("--think", is_flag=True, help="Enable chain-of-thought from the start")
+@click.option("--no-stream", is_flag=True, help="Disable streaming")
+@click.option("--permissions",
+              type=click.Choice(["default", "plan", "accept_edits", "bypass"]),
+              default=None)
+@click.option("--resume", default=None, help="Resume a prior session")
+@click.option("--no-personality", is_flag=True)
+@click.option("--verbose-voice", is_flag=True)
+@click.option("--debug", is_flag=True)
+@click.pass_context
+def cli(ctx, model, think, no_stream, permissions, resume,
+        no_personality, verbose_voice, debug):
+    """Cognos — local-first cognitive agent.
+
+    Run with no subcommand to drop straight into the unified REPL.
+    Inside the REPL, type / for the full command palette
+    (voice, draw, serve, model, sessions, tools, …).
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+    # First-run: if the user has no settings yet, run the init wizard
+    # instead of dumping them into the REPL with a half-wired agent.
+    from core.bootstrap import is_first_run
+    if is_first_run():
+        console.print(
+            "[yellow]no settings yet — running [bold]cognos init[/bold] first.[/yellow]"
+        )
+        ctx.invoke(init_cmd, force=False)
+        return
+    ctx.invoke(
+        interactive,
+        model=model, mode="agentic", think=think, no_stream=no_stream,
+        permissions=permissions, resume=resume,
+        no_personality=no_personality, verbose_voice=verbose_voice,
+        system1=None, system2=None, debug=debug,
+    )
+
+
+@cli.command("init")
+@click.option("--force", is_flag=True, help="Overwrite existing settings without asking")
+def init_cmd(force: bool):
+    """First-run setup: pick models, download Caudate weights, write settings."""
+    from core.bootstrap import cmd_init
+    sys.exit(cmd_init(console, force=force))
+
+
+@cli.command("doctor")
+def doctor_cmd():
+    """Diagnose what's wired and what's missing."""
+    from core.bootstrap import cmd_doctor
+    sys.exit(cmd_doctor(console))
+
+
+@cli.command()
+@click.argument("goal")
+@click.option("--model", default=None, help="LLM model to use (e.g. ollama/llama3, claude-sonnet-4-20250514)")
+@click.option("--criteria", "-c", multiple=True, help="Success criteria for the goal")
+@click.option("--debug", is_flag=True, help="Enable debug logging")
+def run(goal: str, model: str | None, criteria: tuple, debug: bool):
+    """Pursue a goal through the cognitive loop."""
+    setup_logging(verbose=debug)
+
+    console.print(Panel(
+        f"[bold]Cognos Cognitive Architecture[/bold]\n"
+        f"Model: {model or LLM_MODEL}",
+        title="cognos",
+        border_style="blue",
+    ))
+
+    agent = CognosAgent(model=model)
+    result = asyncio.run(agent.pursue_goal(
+        description=goal,
+        success_criteria=list(criteria),
+        verbose=True,
+    ))
+
+    if result.status.value == "achieved":
+        console.print("[green bold]Goal achieved![/green bold]")
+    else:
+        console.print(f"[red bold]Goal {result.status.value}[/red bold]")
+
+
+@cli.command()
+@click.option("--model", default=None, help="LLM model to use")
+@click.option("--mode", type=click.Choice(["agentic", "plan"]), default="agentic",
+              help="'agentic' = real-time tool-calling loop (default). 'plan' = DAG planner.")
+@click.option("--think", is_flag=True, help="Enable chain-of-thought reasoning (agentic mode only)")
+@click.option("--no-stream", is_flag=True, help="Disable token-by-token streaming in agentic mode")
+@click.option("--permissions",
+              type=click.Choice(["default", "plan", "accept_edits", "bypass"]),
+              default=None, help="Permission mode (default: from config)")
+@click.option("--resume", default=None, help="Resume a prior session by ID")
+@click.option("--no-personality", is_flag=True,
+              help="Disable the personality layer (identity + mood + voice)")
+@click.option("--verbose-voice", is_flag=True,
+              help="Print Cognos's inner voice (thinking) to the terminal")
+@click.option("--system1", default=None, help="Fast (System 1) model — enables dual-brain routing when paired with --system2")
+@click.option("--system2", default=None, help="Slow (System 2) model")
+@click.option("--debug", is_flag=True, help="Enable debug logging")
+def interactive(model: str | None, mode: str, think: bool, no_stream: bool,
+                permissions: str | None, resume: str | None,
+                no_personality: bool, verbose_voice: bool,
+                system1: str | None, system2: str | None, debug: bool):
+    """Start an interactive session."""
+    setup_logging(verbose=debug)
+
+    def _render_thinking(blocks):
+        for b in blocks:
+            console.print(Panel(b.thinking, title="thinking", border_style="dim"))
+
+    def _render_inner_voice(entry):
+        console.print(Panel(
+            entry.thinking,
+            title=f"inner voice ({entry.mood_label})",
+            border_style="dim",
+        ))
+
+    agent = CognosAgent(
+        model=model,
+        mode=mode,
+        thinking=think,
+        on_thinking=_render_thinking if think else None,
+        permission_mode=permissions,
+        session_id=resume,
+        personality=not no_personality,
+        verbose_personality=verbose_voice,
+        on_inner_voice=_render_inner_voice if verbose_voice else None,
+        system1=system1,
+        system2=system2,
+    )
+
+    from core.banner import print_startup_banner
+    extras = []
+    if think:
+        extras.append("thinking")
+    if mode == "agentic" and not no_stream:
+        extras.append("streaming")
+    print_startup_banner(
+        agent, console, resumed=bool(resume), extras=extras or None,
+    )
+    prompt_label = "You>" if mode == "agentic" else "Goal>"
+
+    from core.input import CognosPrompt
+    from core.slash_commands import SlashContext, dispatch, SlashResult, is_slash
+    from core.statusline import build_status_values, render_statusline
+    from core.settings import Settings
+    from core.paste import detect_paste
+    from core.file_refs import find_refs, expand_with_attachments
+
+    settings = Settings.load()
+    statusline_template = settings.get("statusline") or ""
+    prompt = CognosPrompt(console=console)
+    slash_ctx = SlashContext(agent=agent, console=console, settings=settings)
+
+    while True:
+        try:
+            if statusline_template:
+                console.print(
+                    f"[dim]{render_statusline(statusline_template, build_status_values(agent))}[/dim]"
+                )
+            text = prompt.ask(f"{prompt_label} ").strip()
+            if not text:
+                continue
+
+            if is_slash(text):
+                result = dispatch(text, slash_ctx)
+                if result is SlashResult.QUIT:
+                    break
+                if result is SlashResult.RESET:
+                    continue
+                if isinstance(result, str) and result:
+                    console.print(result)
+                continue
+
+            # @file refs → attachments
+            attachments: list[str] = []
+            if "@" in text and find_refs(text):
+                text, refs = expand_with_attachments(text, agent.files)
+                attachments.extend(refs)
+            # drag-drop image/PDF detection
+            text, pasted = detect_paste(text, agent.files)
+            attachments.extend(pasted)
+
+            if mode == "agentic":
+                if no_stream:
+                    reply = asyncio.run(agent.chat(text, attachments=attachments or None))
+                    console.print(reply)
+                else:
+                    from ui.display import StreamDisplay
+
+                    async def _stream_turn():
+                        display = StreamDisplay(console=console)
+                        # Inject attachments through the agent so the
+                        # session is persisted with the file_id refs.
+                        if attachments:
+                            return await agent.chat(text, attachments=attachments)
+                        return await display.render(agent.agentic.run_streaming(text))
+
+                    asyncio.run(_stream_turn())
+            else:
+                asyncio.run(agent.pursue_goal(description=text, verbose=True))
+
+        except KeyboardInterrupt:
+            break
+        except Exception as e:
+            console.print(f"[red]Error: {e}[/red]")
+
+    # Show final stats (plan mode only — agentic mode doesn't train strategies)
+    if mode == "plan":
+        strategies = agent.strategies
+        if strategies:
+            console.print("\n[bold]Learned Strategies:[/bold]")
+            for s in strategies:
+                console.print(f"  - {s.name} (confidence: {s.confidence:.2f}): {s.description}")
+
+    console.print("\nGoodbye.")
+
+
+@cli.command()
+@click.option("--model", default=None, help="LLM model to use")
+@click.option("--stt", "stt_backend", type=click.Choice(["moonshine", "whisper"]),
+              default="moonshine", help="Speech-to-text backend")
+@click.option("--stt-model", "stt_model", default=None,
+              help="STT model id (Moonshine: 'moonshine/base'|'moonshine/tiny'; Whisper: 'tiny'|'base'|'small'|...)")
+@click.option("--tts", "tts_backend", type=click.Choice(["kokoro", "piper", "xtts"]),
+              default="kokoro", help="Text-to-speech backend (kokoro = natural human voice)")
+@click.option("--tts-voice", "tts_voice", default=None,
+              help="Voice id (Kokoro: af_heart|af_bella|am_adam|bm_george|... default af_heart)")
+@click.option("--piper-voice", "voice_path", default=None,
+              help="Piper-only: path to .onnx voice file")
+@click.option("--no-personality", is_flag=True, help="Disable the personality layer")
+@click.option("--no-greeting", is_flag=True, help="Skip the opening greeting")
+@click.option("--debug", is_flag=True, help="Enable debug logging")
+def talk(model: str | None, stt_backend: str, stt_model: str | None,
+         tts_backend: str, tts_voice: str | None,
+         voice_path: str | None, no_personality: bool, no_greeting: bool, debug: bool):
+    """Start a voice conversation with Cognos — speak and she speaks back."""
+    setup_logging(verbose=debug)
+
+    tts_label = tts_backend
+    if tts_backend == "kokoro":
+        tts_label += f" ({tts_voice or 'af_heart'})"
+    console.print(Panel(
+        f"[bold]Cognos Voice Mode[/bold]\n"
+        f"LLM: {model or LLM_MODEL}\n"
+        f"STT: {stt_backend}{f' ({stt_model})' if stt_model else ''} | TTS: {tts_label}\n"
+        f"Ctrl+C interrupts speech. Say 'goodbye' to exit.",
+        title="cognos voice",
+        border_style="magenta",
+    ))
+
+    from voice.conversation import VoiceConversation
+
+    agent = CognosAgent(
+        model=model,
+        mode="agentic",
+        permission_mode="bypass",   # voice mode can't approve UI prompts
+        personality=not no_personality,
+    )
+
+    stt_kwargs: dict = {}
+    if stt_model:
+        stt_kwargs["model"] = stt_model
+
+    conv = VoiceConversation(
+        agent=agent,
+        stt=stt_backend,
+        tts=tts_backend,
+        voice=tts_voice,
+        voice_path=voice_path,
+        **stt_kwargs,
+    )
+    try:
+        asyncio.run(conv.run(greeting=not no_greeting))
+    finally:
+        asyncio.run(agent.stop())
+
+
+@cli.group()
+def sessions():
+    """Manage saved conversations."""
+    pass
+
+
+@sessions.command("list")
+def sessions_list():
+    """List saved sessions."""
+    from core.session import SessionManager
+    from config import SESSIONS_DIR
+
+    sm = SessionManager(SESSIONS_DIR)
+    entries = sm.list()
+    if not entries:
+        console.print("[dim]No sessions yet.[/dim]")
+        return
+    for s in entries:
+        title = s.title or "(untitled)"
+        console.print(
+            f"[bold]{s.id}[/bold]  {title}  "
+            f"[dim]({len(s.messages)} msgs, model={s.model}, updated={s.updated_at.isoformat(timespec='seconds')})[/dim]"
+        )
+
+
+@sessions.command("delete")
+@click.argument("session_id")
+def sessions_delete(session_id: str):
+    """Delete a session by ID."""
+    from core.session import SessionManager
+    from config import SESSIONS_DIR
+
+    sm = SessionManager(SESSIONS_DIR)
+    if sm.delete(session_id):
+        console.print(f"Deleted {session_id}")
+    else:
+        console.print(f"[red]Session not found: {session_id}[/red]")
+
+
+@sessions.command("rename")
+@click.argument("session_id")
+@click.argument("title")
+def sessions_rename(session_id: str, title: str):
+    """Rename a session."""
+    from core.session import SessionManager
+    from config import SESSIONS_DIR
+
+    sm = SessionManager(SESSIONS_DIR)
+    if sm.rename(session_id, title):
+        console.print(f"Renamed {session_id} -> {title!r}")
+    else:
+        console.print(f"[red]Session not found: {session_id}[/red]")
+
+
+@cli.command("router")
+@click.option("--model", default=None, help="Primary model (fallback when routing disabled)")
+@click.option("--system1", default=None, help="Fast model")
+@click.option("--system2", default=None, help="Slow model")
+@click.argument("prompts", nargs=-1)
+def router_preview(model: str | None, system1: str | None, system2: str | None, prompts: tuple):
+    """Preview router decisions for one or more prompts without calling any LLM."""
+    from llm.provider import LLMProvider
+    from llm.router import Router, RoutingPolicy
+    from config import SYSTEM_1_MODEL, SYSTEM_2_MODEL, ROUTER_COMPLEXITY_THRESHOLD
+    from rich.table import Table
+
+    s1 = system1 or SYSTEM_1_MODEL or model
+    s2 = system2 or SYSTEM_2_MODEL or model
+    if not s1 or not s2:
+        console.print("[red]Configure --system1/--system2 (or SYSTEM_1_MODEL/SYSTEM_2_MODEL).[/red]")
+        return
+
+    fast = LLMProvider(model=s1)
+    slow = LLMProvider(model=s2)
+    r = Router(fast=fast, slow=slow, policy=RoutingPolicy(complexity_threshold=ROUTER_COMPLEXITY_THRESHOLD))
+
+    if not prompts:
+        prompts = (
+            "list files here",
+            "what is 2+2",
+            "analyze the architecture and explain the tradeoffs",
+            "design a caching layer for the API",
+            "refactor this to use async",
+        )
+
+    table = Table(title="Router preview")
+    table.add_column("prompt")
+    table.add_column("tier")
+    table.add_column("score")
+    table.add_column("reasons")
+    for p in prompts:
+        d = r.choose(messages=[{"role": "user", "content": p}])
+        preview = p if len(p) <= 60 else p[:57] + "…"
+        table.add_row(preview, d.tier, f"{d.score:.2f}", ", ".join(d.reasons))
+    console.print(table)
+
+
+@cli.group()
+def personality():
+    """Inspect and tune Cognos's personality (traits, mood, inner voice)."""
+    pass
+
+
+@personality.command("show")
+def personality_show():
+    """Show the current identity, mood, and recent inner-voice entries."""
+    from personality import PersonalityEngine
+    from config import DATA_DIR
+
+    engine = PersonalityEngine.load(DATA_DIR)
+    console.print(Panel(engine.identity.describe(), title="identity", border_style="cyan"))
+    console.print(Panel(
+        engine.mood.system_prompt_fragment(),
+        title=f"mood ({engine.mood.label()})",
+        border_style="magenta",
+    ))
+
+
+@personality.command("set")
+@click.argument("trait")
+@click.argument("value", type=float)
+def personality_set(trait: str, value: float):
+    """Set a trait or value to a given [0, 1] level."""
+    from personality.identity import Identity
+    from config import IDENTITY_PATH
+
+    identity = Identity.load(IDENTITY_PATH)
+    if not hasattr(identity, trait):
+        console.print(f"[red]Unknown trait: {trait}[/red]")
+        console.print(f"Available: {sorted(identity.model_fields.keys())}")
+        return
+    setattr(identity, trait, max(0.0, min(1.0, value)))
+    identity.save(IDENTITY_PATH)
+    console.print(f"Set {trait} = {getattr(identity, trait):.2f}")
+
+
+@personality.command("reset")
+@click.option("--mood", "reset_mood", is_flag=True, help="Reset mood only")
+@click.option("--identity", "reset_identity", is_flag=True, help="Reset identity only")
+def personality_reset(reset_mood: bool, reset_identity: bool):
+    """Reset personality state to defaults."""
+    from personality.identity import Identity
+    from personality.mood import MoodState
+    from config import IDENTITY_PATH, MOOD_PATH
+
+    do_both = not (reset_mood or reset_identity)
+    if reset_identity or do_both:
+        Identity().save(IDENTITY_PATH)
+        console.print("Identity reset to defaults.")
+    if reset_mood or do_both:
+        MoodState().save(MOOD_PATH)
+        console.print("Mood reset to neutral.")
+
+
+@cli.command("models")
+@click.option("--vram", "vram_mb", type=int, default=None,
+              help="Override available VRAM in MB (defaults to nvidia-smi).")
+def list_models(vram_mb: int | None):
+    """List available Ollama models with capability flags + VRAM fit."""
+    import asyncio
+    from llm.models import (
+        ModelRegistry, estimate_vram, compare_to_available,
+        detect_available_vram_mb, pick_best_fit,
+    )
+
+    async def _go():
+        reg = ModelRegistry()
+        await reg.refresh()
+        return reg.models()
+
+    models = asyncio.run(_go())
+    if not models:
+        console.print("[yellow]No models detected. Is Ollama running?[/yellow]")
+        return
+
+    available_mb = vram_mb if vram_mb is not None else detect_available_vram_mb()
+
+    from rich.table import Table
+    title = "Available Models"
+    if available_mb:
+        title += f"  [GPU: {available_mb} MB]"
+    table = Table(title=title)
+    table.add_column("id")
+    table.add_column("provider")
+    table.add_column("tools")
+    table.add_column("json")
+    table.add_column("ctx")
+    table.add_column("size")
+    table.add_column("VRAM (Q4)")
+    table.add_column("fit")
+    for m in sorted(models, key=lambda x: (x.provider, x.name)):
+        size = f"{m.size_bytes / (1024**3):.1f}GB" if m.size_bytes else "-"
+        est = estimate_vram(m.id)
+        if est:
+            vram_str = f"{est.vram_mb} MB"
+            if available_mb:
+                status = compare_to_available(est.vram_mb, available_mb)
+                fit = {
+                    "fits": "[green]✅ fits[/green]",
+                    "tight": "[yellow]⚠ tight[/yellow]",
+                    "wont-fit": "[red]❌ won't fit[/red]",
+                }[status]
+            else:
+                fit = "[dim]?[/dim]"
+        else:
+            vram_str = "-"
+            fit = "[dim]cloud/?[/dim]"
+        table.add_row(
+            m.id,
+            m.provider,
+            "✓" if m.supports_tool_calling else "-",
+            "✓" if m.supports_json_mode else "-",
+            f"{m.context_window:,}",
+            size,
+            vram_str,
+            fit,
+        )
+    console.print(table)
+    if available_mb:
+        ids = [m.id for m in models if m.provider == "ollama"]
+        best = pick_best_fit(ids, available_mb)
+        if best:
+            mid, est, status = best
+            badge = {"fits": "[green]✅", "tight": "[yellow]⚠"}.get(status, "")
+            console.print(
+                f"\n{badge} Best local fit:[/] {mid}  "
+                f"({est.params_b}B, ~{est.vram_mb} MB)"
+            )
+
+
+@cli.command("mcp-serve")
+def mcp_serve():
+    """Run Cognos as an MCP server (stdio). Exposes all Cognos tools to MCP clients."""
+    import asyncio
+    from cognos_mcp.server import build_server
+
+    server = build_server()
+    asyncio.run(server.run_stdio_async())
+
+
+@cli.command("serve")
+@click.option("--host", default="127.0.0.1", help="Bind address")
+@click.option("--port", default=8000, type=int, help="Bind port")
+@click.option("--reload", is_flag=True, help="Auto-reload on code change (dev)")
+def serve(host: str, port: int, reload: bool):
+    """Run Cognos as an HTTP API (POST /chat, GET /sessions, GET /tools, GET /models)."""
+    # Initialise logging so cognos module loggers (api/, core/, nn/)
+    # actually emit. Without this, INFO from constitutional critique,
+    # caudate observations, etc. silently drops on the floor.
+    setup_logging(verbose=True)
+    import uvicorn
+    uvicorn.run(
+        "api.server:create_app",
+        host=host, port=port, reload=reload, factory=True,
+    )
+
+
+@cli.group()
+def nn():
+    """Caudate — Cognos's action-selection neural net. Train, eval, status."""
+    pass
+
+
+# `cognos caudate ...` reads better than `cognos nn ...` once you know
+# the name. Both work.
+cli.add_command(nn, name="caudate")
+
+
+@nn.command("train")
+@click.option("--max-steps", default=None, type=int, help="Override max_steps")
+@click.option("--batch-size", default=None, type=int)
+@click.option("--lr", default=None, type=float)
+@click.option("--from-scratch", is_flag=True, help="Ignore existing checkpoint")
+@click.option("--debug", is_flag=True)
+def nn_train(max_steps: int | None, batch_size: int | None, lr: float | None,
+             from_scratch: bool, debug: bool):
+    """Train the controller on saved sessions."""
+    setup_logging(verbose=debug)
+    from nn.config import NNConfig
+    from nn.data import load_corpus_from_sessions
+    from nn.trainer import Trainer, build_fresh
+
+    cfg = NNConfig()
+    if max_steps is not None: cfg.max_steps = max_steps
+    if batch_size is not None: cfg.batch_size = batch_size
+    if lr is not None: cfg.learning_rate = lr
+
+    corpus = load_corpus_from_sessions()
+    console.print(f"[dim]loaded {len(corpus)} training samples from saved sessions[/dim]")
+
+    if not from_scratch and Path(cfg.checkpoint_path).exists():
+        trainer = Trainer.load(cfg)
+        console.print(f"[dim]resumed from {cfg.checkpoint_path} (step {trainer.step})[/dim]")
+    else:
+        trainer = build_fresh(cfg)
+        console.print(f"[dim]fresh trainer, params={trainer.model.num_parameters():,}[/dim]")
+
+    # Seed vocab from any tool name appearing in the corpus + Cognos's
+    # currently registered tools (so unseen tools still get an id).
+    from execution.executor import Executor
+    for name in Executor(load_plugins=False).list_tools():
+        trainer.vocab.add(name)
+    for s in corpus:
+        trainer.vocab.add(s.target_tool)
+
+    if not corpus:
+        console.print("[yellow]No training data yet. Use Cognos for a few sessions first, "
+                      "or seed via the replay buffer.[/yellow]")
+        return
+
+    history = trainer.fit(corpus)
+    if history:
+        last = history[-1]
+        console.print(Panel(
+            f"steps: {last.step}\n"
+            f"final loss: {last.loss_total:.4f}\n"
+            f"tool_acc: {last.tool_acc:.2f}  tier_acc: {last.tier_acc:.2f}  "
+            f"think_acc: {last.think_acc:.2f}\n"
+            f"checkpoint: {cfg.checkpoint_path}",
+            title="nn train", border_style="green",
+        ))
+
+
+@nn.command("train-forge")
+@click.option("--max-steps", default=400, type=int, help="Training steps")
+@click.option("--batch-size", default=16, type=int)
+@click.option("--lr", default=None, type=float)
+@click.option("--from-scratch", is_flag=True,
+              help="Ignore existing checkpoint, train trunk + heads fresh")
+@click.option("--debug", is_flag=True)
+def nn_train_forge(max_steps: int, batch_size: int, lr: float | None,
+                   from_scratch: bool, debug: bool):
+    """Train Caudate's feature_success head on Forge outcomes (ADR 0006 Phase A).
+
+    Reads `data/nn/feature_outcomes.jsonl`, converts each row to a
+    one-message ConversationSample tagged with the originating model, and
+    resumes the existing checkpoint. Other heads see no targets in
+    these samples (optional_target=True), so their weights drift only
+    via the shared trunk — which is what we want for transfer learning."""
+    setup_logging(verbose=debug)
+    from nn.config import NNConfig
+    from nn.data import load_corpus_from_feature_outcomes
+    from nn.trainer import Trainer, build_fresh
+
+    cfg = NNConfig()
+    cfg.max_steps = max_steps
+    cfg.batch_size = batch_size
+    if lr is not None:
+        cfg.learning_rate = lr
+
+    corpus = load_corpus_from_feature_outcomes()
+    console.print(
+        f"[dim]loaded {len(corpus)} feature-outcome samples from "
+        f"data/nn/feature_outcomes.jsonl[/dim]"
+    )
+    if not corpus:
+        console.print(
+            "[yellow]No feature outcomes yet. Run Forge first to produce labels.[/yellow]"
+        )
+        return
+
+    n_success = sum(1 for s in corpus if (s.target_feature_success or 0) >= 0.5)
+    console.print(
+        f"[dim]label balance: {n_success} success / {len(corpus) - n_success} fail[/dim]"
+    )
+
+    if not from_scratch and Path(cfg.checkpoint_path).exists():
+        trainer = Trainer.load(cfg)
+        # The loaded trainer's `step` is from prior runs — reset the
+        # counter so `max_steps` applies to this training pass alone.
+        trainer.cfg.max_steps = trainer.step + max_steps
+        console.print(
+            f"[dim]resumed from {cfg.checkpoint_path} "
+            f"(prior step={trainer.step}, will run {max_steps} more)[/dim]"
+        )
+    else:
+        trainer = build_fresh(cfg)
+        console.print(
+            f"[dim]fresh trainer, params={trainer.model.num_parameters():,}[/dim]"
+        )
+
+    # Register the source vocab so model_id strings get stable embedding
+    # slots. This is the same idempotent `add` flow that collate uses.
+    for s in corpus:
+        if s.model_source:
+            trainer.source_vocab.add(s.model_source)
+
+    history = trainer.fit(corpus)
+    if history:
+        last = history[-1]
+        feat_loss = next(
+            (m for m in reversed(history)
+             if getattr(m, "loss_total", None) is not None),
+            None,
+        )
+        console.print(Panel(
+            f"steps: {last.step}\n"
+            f"final total loss: {last.loss_total:.4f}\n"
+            f"checkpoint: {cfg.checkpoint_path}\n"
+            f"head: feature_success",
+            title="nn train-forge", border_style="green",
+        ))
+
+
+@nn.command("train-public")
+@click.option("--corpus", "corpus_path", required=True, type=str,
+              help="Path to a local HuggingFace cache (the directory "
+                   "containing the .arrow shards). Or an HF Hub id "
+                   "(slash-separated) — that path is forwarded to "
+                   "load_corpus_from_hf for streaming.")
+@click.option("--max-rows", default=10000, type=int,
+              help="Cap on rows read from the corpus (smoke-friendly default)")
+@click.option("--max-steps", default=500, type=int)
+@click.option("--batch-size", default=16, type=int)
+@click.option("--lr", default=None, type=float)
+@click.option("--from-scratch", is_flag=True,
+              help="Ignore existing checkpoint; train trunk + heads fresh")
+@click.option("--no-tool-weight", default=None, type=float,
+              help="Class-balanced loss weight on the contrastive tool head's "
+                   "<no_tool> slot (slot 0). 1.0 = unweighted; <1.0 = "
+                   "downweight; >1.0 = upweight. Use to correct slot-0 bias "
+                   "from corpora dominated by <no_tool> rows.")
+@click.option("--debug", is_flag=True)
+def nn_train_public(
+    corpus_path: str, max_rows: int, max_steps: int, batch_size: int,
+    lr: float | None, from_scratch: bool, no_tool_weight: float | None,
+    debug: bool,
+):
+    """Train Caudate on a public tool-use / reasoning corpus.
+
+    Auto-detects on-disk layout: a path containing *.arrow files is
+    treated as a local HF cache (no network); a slash-separated name
+    is forwarded to load_corpus_from_hf as an HF Hub id.
+
+    Sample emission:
+      - Assistant turns with tool_calls → one sample per call (open-vocab tool head trains)
+      - Assistant turns without tool_calls → one sample with target_tool="<no_tool>"
+        (trunk + "don't call anything" signal — useful for reasoning corpora
+         like Kimi-K2.5-Reasoning that have no tool calls at all)
+    """
+    setup_logging(verbose=debug)
+    from pathlib import Path as _P
+    from nn.config import NNConfig
+    from nn.data import (
+        load_corpus_from_glaive_json, load_corpus_from_hf,
+        load_corpus_from_local_arrow, load_corpus_from_oai_jsonl,
+    )
+    from nn.trainer import Trainer, build_fresh
+
+    cfg = NNConfig()
+    cfg.max_steps = max_steps
+    cfg.batch_size = batch_size
+    if lr is not None:
+        cfg.learning_rate = lr
+    if no_tool_weight is not None:
+        cfg.tool_no_tool_class_weight = no_tool_weight
+        console.print(
+            f"[dim]tool_no_tool_class_weight = {no_tool_weight} "
+            f"(slot-0 cross-entropy rebalance)[/dim]"
+        )
+
+    p = _P(corpus_path)
+    if p.exists() and p.is_file() and p.suffix == ".json":
+        corpus = load_corpus_from_glaive_json(p, max_rows=max_rows)
+    elif p.exists() and p.is_file() and p.suffix == ".jsonl":
+        corpus = load_corpus_from_oai_jsonl(p, max_rows=max_rows)
+    elif p.exists() and p.is_dir():
+        # Prefer arrow shards; fall back to a single JSON file inside.
+        if list(p.glob("*.arrow")):
+            corpus = load_corpus_from_local_arrow(p, max_rows=max_rows)
+        else:
+            json_files = sorted(p.glob("*.json"))
+            if json_files:
+                corpus = load_corpus_from_glaive_json(
+                    json_files[0], max_rows=max_rows,
+                )
+            else:
+                corpus = []
+    else:
+        corpus = load_corpus_from_hf(
+            corpus_path, max_rows=max_rows, streaming=True,
+        )
+    console.print(f"[dim]loaded {len(corpus)} samples from {corpus_path}[/dim]")
+    if not corpus:
+        console.print("[yellow]No samples loaded. Check the path/dataset shape.[/yellow]")
+        return
+
+    # Quick label balance + source distribution sanity check
+    tool_targets = [s.target_tool for s in corpus]
+    n_no_tool = sum(1 for t in tool_targets if t == "<no_tool>")
+    n_with_tool = len(corpus) - n_no_tool
+    console.print(
+        f"[dim]targets: {n_with_tool} tool-call / {n_no_tool} <no_tool>[/dim]"
+    )
+
+    if not from_scratch and Path(cfg.checkpoint_path).exists():
+        trainer = Trainer.load(cfg)
+        trainer.cfg.max_steps = trainer.step + max_steps
+        console.print(
+            f"[dim]resumed from {cfg.checkpoint_path} "
+            f"(prior step={trainer.step}, will run {max_steps} more)[/dim]"
+        )
+    else:
+        trainer = build_fresh(cfg)
+        console.print(
+            f"[dim]fresh trainer, params={trainer.model.num_parameters():,}[/dim]"
+        )
+
+    for s in corpus:
+        if s.model_source:
+            trainer.source_vocab.add(s.model_source)
+        if s.target_tool:
+            trainer.vocab.add(s.target_tool)
+
+    history = trainer.fit(corpus)
+    if history:
+        last = history[-1]
+        console.print(Panel(
+            f"steps: {last.step}\n"
+            f"final total loss: {last.loss_total:.4f}\n"
+            f"tool_acc: {last.tool_acc:.2f}\n"
+            f"checkpoint: {cfg.checkpoint_path}",
+            title="nn train-public", border_style="green",
+        ))
+
+
+@nn.command("eval")
+def nn_eval():
+    """Run evaluation on the held-out split."""
+    from nn.config import NNConfig
+    from nn.data import load_corpus_from_sessions, split_train_eval
+    from nn.trainer import Trainer
+
+    cfg = NNConfig()
+    if not Path(cfg.checkpoint_path).exists():
+        console.print(f"[red]No checkpoint at {cfg.checkpoint_path}. Train first.[/red]")
+        return
+    trainer = Trainer.load(cfg)
+    corpus = load_corpus_from_sessions()
+    _, ev = split_train_eval(corpus, cfg.eval_split, cfg.seed)
+    metrics = trainer.evaluate(ev)
+    console.print(metrics or "[dim](no eval data)[/dim]")
+
+
+@nn.command("status")
+def nn_status():
+    """Show controller info, training step, recent advisor predictions."""
+    from nn.config import NNConfig
+    cfg = NNConfig()
+    meta_path = Path(cfg.metadata_path)
+    if not meta_path.exists():
+        console.print("[dim]No NN trained yet. Run: cognos nn train[/dim]")
+        return
+    import json as _json
+    meta = _json.loads(meta_path.read_text())
+    console.print(Panel(
+        f"params: {meta['n_params']:,}\n"
+        f"step: {meta['step']}\n"
+        f"saved_at: {meta['saved_at']}\n"
+        f"checkpoint: {cfg.checkpoint_path}",
+        title="nn status",
+    ))
+    log = Path(cfg.advisor_log_path)
+    if log.exists():
+        lines = log.read_text().splitlines()[-5:]
+        if lines:
+            console.print("[dim]recent predictions:[/dim]")
+            for ln in lines:
+                console.print(f"  {ln}")
+
+
+@nn.command("export")
+@click.argument("out_path")
+def nn_export(out_path: str):
+    """Copy the latest checkpoint + metadata to a path you can share."""
+    import shutil
+    from nn.config import NNConfig
+    cfg = NNConfig()
+    out = Path(out_path)
+    out.mkdir(parents=True, exist_ok=True)
+    for src in (Path(cfg.checkpoint_path), Path(cfg.metadata_path)):
+        if src.exists():
+            shutil.copy2(src, out / src.name)
+    console.print(f"exported → {out}")
+
+
+@nn.group("nas")
+def nn_nas():
+    """Caudate's neural architecture search — let her evolve her own brain."""
+    pass
+
+
+@nn_nas.command("run")
+@click.option("--strategy", "strategy_name",
+              type=click.Choice(["random", "evolutionary", "rl", "darts", "hyperband"]),
+              default="random", help="NAS algorithm")
+@click.option("--trials", default=8, type=int, help="How many architectures to try (sample-and-score)")
+@click.option("--steps", default=200, type=int, help="Train steps per trial")
+@click.option("--seed", default=42, type=int)
+@click.option("--epochs", default=5, type=int, help="DARTS only: epochs of supernet training")
+@click.option("--population", default=8, type=int, help="evolutionary only: population size")
+@click.option("--max-budget", default=800, type=int, help="hyperband only: max budget")
+@click.option("--min-budget", default=50, type=int, help="hyperband only: min budget")
+def nn_nas_run(strategy_name: str, trials: int, steps: int, seed: int,
+               epochs: int, population: int, max_budget: int, min_budget: int):
+    """Run NAS with the chosen strategy."""
+    from nn.nas import Searcher
+    from nn.nas.searcher import SearcherConfig
+    from nn.nas.strategies import make_strategy
+    from nn.nas.strategies.base import StrategyConfig
+
+    scfg = StrategyConfig(n_trials=trials, train_steps_per_trial=steps, seed=seed)
+
+    if strategy_name == "evolutionary":
+        strategy = make_strategy("evolutionary", config=scfg, population_size=population)
+    elif strategy_name == "rl":
+        strategy = make_strategy("rl", config=scfg)
+    elif strategy_name == "darts":
+        strategy = make_strategy("darts", config=scfg, epochs=epochs)
+    elif strategy_name == "hyperband":
+        base = make_strategy("random", config=scfg)
+        strategy = make_strategy("hyperband", config=scfg, base=base,
+                                 max_budget=max_budget, min_budget=min_budget)
+    else:
+        strategy = make_strategy("random", config=scfg)
+
+    sconf = SearcherConfig(n_trials=trials, train_steps_per_trial=steps, seed=seed)
+    s = Searcher(cfg=sconf, strategy=strategy)
+    console.print(Panel(
+        f"strategy: [bold]{strategy_name}[/bold]\n"
+        f"trials: {trials}  ·  steps/trial: {steps}  ·  seed: {seed}",
+        title="caudate nas", border_style="cyan",
+    ))
+    summary = s.search()
+    if summary["status"] == "bailed":
+        console.print(f"[yellow]bailed: {summary['reason']}, "
+                      f"corpus={summary['corpus_size']}[/yellow]")
+        return
+    if summary["status"] == "complete-darts":
+        console.print(f"\n[green]DARTS done[/green]")
+        console.print(f"discrete arch: {summary['discrete_arch']}")
+        console.print(f"params: {summary['n_params']:,}")
+        return
+    console.print(f"\n[bold]done[/bold] · {summary['n_trials']} trials")
+    if summary.get("champion"):
+        console.print(f"[green]champion:[/green] {summary['champion']}")
+    else:
+        console.print("[yellow]no champion (all trials failed)[/yellow]")
+
+
+@nn_nas.command("status")
+def nn_nas_status():
+    """Show current champion + recent trials."""
+    from nn.nas.store import NASStore
+    store = NASStore()
+    champ = store.champion()
+    if champ is None:
+        console.print("[dim]no champion yet — run `cognos caudate nas run`[/dim]")
+    else:
+        spec = champ.get("spec", {})
+        result = champ.get("result", {})
+        console.print(Panel(
+            f"id: {champ.get('id')}\n"
+            f"saved_at: {champ.get('saved_at')}\n"
+            f"d_model={spec.get('d_model')} L={spec.get('n_layers')} "
+            f"h={spec.get('n_heads')} ff={spec.get('d_ff_multiplier')}\n"
+            f"fitness: {result.get('fitness')}\n"
+            f"composite acc: {result.get('composite')}\n"
+            f"params: {result.get('n_params'):,}",
+            title="champion", border_style="green",
+        ))
+    history = store.history()
+    if history:
+        console.print(f"\n[dim]{len(history)} total trials in history[/dim]")
+        from rich.table import Table
+        t = Table(title="recent trials")
+        t.add_column("id"); t.add_column("d_model"); t.add_column("L")
+        t.add_column("h"); t.add_column("ff"); t.add_column("fitness")
+        t.add_column("tool_acc")
+        for h in history[-10:]:
+            sp, r = h.get("spec", {}), h.get("result", {})
+            t.add_row(
+                h.get("id", "")[:8], str(sp.get("d_model")),
+                str(sp.get("n_layers")), str(sp.get("n_heads")),
+                str(sp.get("d_ff_multiplier")),
+                f"{r.get('fitness', 0):.3f}",
+                f"{r.get('tool_acc', 0):.2f}",
+            )
+        console.print(t)
+
+
+@nn_nas.command("promote")
+def nn_nas_promote():
+    """Promote the current NAS champion to be the active Caudate."""
+    from nn.config import NNConfig
+    from nn.nas.store import NASStore
+    cfg = NNConfig()
+    store = NASStore()
+    if store.promote_to_main(cfg.checkpoint_path):
+        console.print(f"[green]promoted champion → {cfg.checkpoint_path}[/green]")
+    else:
+        console.print("[yellow]no champion to promote[/yellow]")
+
+
+@nn_nas.command("plateau")
+def nn_nas_plateau():
+    """Show plateau-detection state (auto-fire conditions)."""
+    from nn.nas.scheduler import PlateauScheduler
+    sched = PlateauScheduler()
+    import json as _json
+    console.print(_json.dumps(sched.status(), indent=2))
+
+
+@cli.command("draw")
+@click.argument("prompt")
+@click.option("--backend", type=click.Choice(["diffusers", "comfyui", "litellm"]),
+              default="diffusers", help="Image-gen backend")
+@click.option("--model", default=None,
+              help="Backend-specific model id (e.g. 'stabilityai/sdxl-turbo', "
+                   "'black-forest-labs/FLUX.1-schnell', 'openai/gpt-image-1')")
+@click.option("--size", default="1024x1024", help="WxH (default 1024x1024)")
+@click.option("--negative", default="", help="Negative prompt")
+@click.option("--seed", default=None, type=int, help="Random seed")
+@click.option("--steps", default=None, type=int, help="Inference steps")
+@click.option("--out", default=None, help="Output PNG path (default: data/files/<id>.png)")
+@click.option("--debug", is_flag=True, help="Enable debug logging")
+def draw_cmd(prompt: str, backend: str, model: str | None, size: str,
+             negative: str, seed: int | None, steps: int | None,
+             out: str | None, debug: bool):
+    """Generate an image from a prompt."""
+    setup_logging(verbose=debug)
+    from core.image import make_image_gen, generate_to_file_store
+    from core.files import FileStore
+    from config import FILES_DIR
+
+    backend_kwargs: dict = {}
+    if model:
+        if backend == "comfyui":
+            backend_kwargs["checkpoint"] = model
+        else:
+            backend_kwargs["model"] = model
+
+    async def _go():
+        store = FileStore(root=FILES_DIR)
+        gen = make_image_gen(backend, **backend_kwargs)
+        kwargs: dict = {}
+        if negative: kwargs["negative_prompt"] = negative
+        if seed is not None: kwargs["seed"] = seed
+        if steps is not None: kwargs["steps"] = steps
+        record = await generate_to_file_store(gen, store, prompt, size=size, **kwargs)
+        return record
+
+    console.print(Panel(
+        f"[bold]Generating image[/bold]\nbackend: {backend}\nprompt: {prompt}\nsize: {size}",
+        border_style="magenta",
+    ))
+    record = asyncio.run(_go())
+
+    final_path = Path(record.path)
+    if out:
+        out_path = Path(out)
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_bytes(final_path.read_bytes())
+        final_path = out_path
+
+    console.print(f"[green]Saved:[/green] {final_path}")
+    console.print(f"[dim]file_id: {record.id}[/dim]")
+
+
+@cli.command("bench")
+@click.option("--out", "out", default=None, help="JSON output path (default: data/bench/<utc>.json)")
+def bench(out: str | None):
+    """Run the benchmark suite (no LLM calls — uses an in-process stub)."""
+    from bench.runner import main_async
+    asyncio.run(main_async(Path(out) if out else None))
+
+
+@cli.command()
+def update():
+    """Pull the latest version (git checkout) or upgrade pip install."""
+    from core.updater import update as _update
+    result = _update()
+    border = "green" if result.changed else "yellow"
+    console.print(Panel(
+        f"mode: {result.mode}\n{result.summary}\n\n{result.details}".strip(),
+        title="cognos update",
+        border_style=border,
+    ))
+
+
+@cli.group()
+def cron():
+    """Scheduled prompts."""
+    pass
+
+
+@cron.command("list")
+def cron_list():
+    """List scheduled jobs."""
+    from core.scheduler import CronStore
+    from rich.table import Table
+    store = CronStore(Path("data/cron.json"))
+    jobs = store.list()
+    if not jobs:
+        console.print("[dim]No scheduled jobs.[/dim]")
+        return
+    table = Table(title="Cron")
+    table.add_column("id"); table.add_column("schedule"); table.add_column("next"); table.add_column("prompt")
+    for j in jobs:
+        table.add_row(j.id, j.schedule, j.next_run or "-", j.prompt[:60])
+    console.print(table)
+
+
+@cron.command("add")
+@click.argument("schedule")
+@click.argument("prompt")
+def cron_add(schedule: str, prompt: str):
+    """Schedule a recurring prompt. SCHEDULE is e.g. 'every 1h' or 'daily 09:00'."""
+    from core.scheduler import CronStore
+    store = CronStore(Path("data/cron.json"))
+    try:
+        job = store.add(prompt=prompt, schedule=schedule)
+    except Exception as e:
+        console.print(f"[red]{e}[/red]")
+        return
+    console.print(f"Scheduled {job.id}: next={job.next_run}")
+
+
+@cron.command("remove")
+@click.argument("job_id")
+def cron_remove(job_id: str):
+    """Remove a scheduled job."""
+    from core.scheduler import CronStore
+    store = CronStore(Path("data/cron.json"))
+    if store.remove(job_id):
+        console.print(f"Removed {job_id}")
+    else:
+        console.print(f"[red]Not found: {job_id}[/red]")
+
+
+@cron.command("run")
+@click.option("--model", default=None, help="Model used to fire jobs")
+def cron_run(model: str | None):
+    """Run the scheduler loop in the foreground until Ctrl+C."""
+    from core.scheduler import CronStore, run_scheduler
+
+    async def _go():
+        store = CronStore(Path("data/cron.json"))
+        agent_local = CognosAgent(model=model, mode="agentic", permission_mode="bypass")
+
+        async def fire(job):
+            console.print(f"[dim]cron fire {job.id}: {job.prompt}[/dim]")
+            try:
+                reply = await agent_local.chat(job.prompt)
+                console.print(Panel(reply, title=f"cron {job.id}", border_style="cyan"))
+            except Exception as e:
+                console.print(f"[red]cron {job.id} failed: {e}[/red]")
+
+        await run_scheduler(store, fire)
+
+    try:
+        asyncio.run(_go())
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Scheduler stopped.[/yellow]")
+
+
+@sessions.command("export")
+@click.argument("session_id")
+@click.option("--format", "fmt", type=click.Choice(["markdown", "md", "json", "html"]), default="markdown")
+@click.option("--out", "out", default=None, help="Output path (defaults to data/exports/<id>.<ext>)")
+def sessions_export(session_id: str, fmt: str, out: str | None):
+    """Export a session to a file."""
+    from core.session import SessionManager
+    from core.export import export_session
+    from config import SESSIONS_DIR
+    sm = SessionManager(SESSIONS_DIR)
+    s = sm.load(session_id)
+    if s is None:
+        console.print(f"[red]Session not found: {session_id}[/red]")
+        return
+    ext = {"markdown": "md", "md": "md", "json": "json", "html": "html"}[fmt]
+    path = Path(out) if out else Path(f"data/exports/{session_id}.{ext}")
+    export_session(s, path, format=fmt)
+    console.print(f"Exported → {path}")
+
+
+@cli.command()
+def info():
+    """Show system information."""
+    from execution.executor import Executor
+    from memory.procedural import ProceduralMemory
+
+    executor = Executor()
+    proc = ProceduralMemory()
+
+    console.print(Panel(
+        f"[bold]Available Tools:[/bold]\n{executor.tool_descriptions()}\n\n"
+        f"[bold]Learned Strategies:[/bold] {len(proc.get_strategies())}\n"
+        f"[bold]Performance Logs:[/bold] {len(proc.get_performance_history())}",
+        title="cognos info",
+        border_style="green",
+    ))
+
+
+# ────────────────────────── Forge subcommand ─────────────────────────
+# `cognos forge ...` — autonomous coding harness ported from LocalForge.
+# Bootstrap a feature backlog from a project description, drive the
+# orchestrator, manage projects/features. State lives in data/cognos.db
+# (forge_* tables). See planning/forge_models.py for the schema and
+# planning/orchestrator.py for execution.
+
+
+@cli.group()
+def forge():
+    """Forge — autonomous coding harness. Bootstrap features, run agents.
+
+    Quick start:
+      cognos forge new "my-app" --description "..." --folder /path/to/code
+      cognos forge bootstrap "build a recipe site" --project 1 --stack web
+      cognos forge feature list --project 1
+      cognos forge start --project 1            # run agents on the backlog
+    """
+    pass
+
+
+@forge.command("new")
+@click.argument("name")
+@click.option("--description", default=None, help="Project description")
+@click.option("--folder", default=None,
+              help="Project working directory (default: sandbox/projects/<slug>/)")
+def forge_new(name: str, description: str | None, folder: str | None):
+    """Create a new forge project."""
+    from planning.forge_models import init, create_project
+    from pathlib import Path
+    import re
+
+    init()
+    if folder is None:
+        slug = re.sub(r"[^a-zA-Z0-9_-]+", "-", name.lower()).strip("-")
+        folder = str(Path("sandbox/projects") / slug)
+    Path(folder).mkdir(parents=True, exist_ok=True)
+    pid = create_project(name, description, folder)
+    console.print(
+        f"[green]✓[/green] Created project [bold]{name}[/bold] "
+        f"(id={pid}) at [cyan]{folder}[/cyan]"
+    )
+
+
+@forge.command("projects")
+def forge_projects():
+    """List all forge projects."""
+    from planning.forge_models import init, list_projects
+    init()
+    rows = list_projects()
+    if not rows:
+        console.print("[dim]No forge projects yet. "
+                      "Try: cognos forge new \"my-app\"[/dim]")
+        return
+    for p in rows:
+        console.print(
+            f"  [bold]#{p['id']}[/bold] {p['name']} "
+            f"[dim]({p['status']})[/dim] → [cyan]{p['folder_path']}[/cyan]"
+        )
+        if p["description"]:
+            console.print(f"      [dim]{p['description']}[/dim]")
+
+
+@forge.command("bootstrap")
+@click.argument("goal")
+@click.option("--project", "-p", "project_id", type=int, required=True,
+              help="Project id to add features to (use `cognos forge projects`)")
+@click.option("--stack", multiple=True,
+              help="Stack hints, e.g. --stack python --stack fastapi. "
+                   "Repeat for multi-tag.")
+@click.option("--max-features", default=15, type=int,
+              help="Cap the size of the generated backlog")
+@click.option("--dry-run", is_flag=True,
+              help="Print the proposed backlog but don't write to DB")
+def forge_bootstrap(goal: str, project_id: int, stack: tuple[str, ...],
+                    max_features: int, dry_run: bool):
+    """Decompose a project description into a forge feature backlog.
+
+    Calls the System 2 LLM via the bootstrapper prompt; produces a
+    structured backlog with priorities, dependencies, and a suggested
+    verify_command per feature.
+    """
+    from planning.forge_models import (
+        init, get_project, create_feature, add_dependency,
+    )
+    from planning.planner import Planner
+    from llm.provider import LLMProvider
+    import asyncio
+
+    setup_logging(verbose=False)
+    init()
+
+    proj = get_project(project_id)
+    if not proj:
+        console.print(f"[red]✗ Project {project_id} not found.[/red] "
+                      f"List projects: cognos forge projects")
+        raise click.Abort()
+
+    console.print(
+        f"[dim]Bootstrapping features for project "
+        f"[bold]{proj['name']}[/bold] "
+        f"(stack={list(stack) or 'auto'}, max={max_features})…[/dim]"
+    )
+
+    async def _bootstrap():
+        # Bootstrapping is heavy reasoning work — use the System 2 (slow)
+        # Local-first: bootstrap is a structured-output task, well within
+        # reach of System-1 Ollama models (GLM, Qwen, Llama). Only falls
+        # back to System-2 (often a cloud model) if no System-1 is set.
+        from core.settings import Settings
+        from config import SYSTEM_1_MODEL, SYSTEM_2_MODEL
+        settings = Settings.load()
+        chosen = (
+            settings.get("system1") or SYSTEM_1_MODEL
+            or settings.get("system2") or SYSTEM_2_MODEL
+            or LLM_MODEL
+        )
+        console.print(f"[dim]Using model: {chosen}[/dim]")
+        llm = LLMProvider(model=chosen)
+        planner = Planner(llm)
+        # If the chosen model is an Anthropic model, the user likely
+        # authenticates via the Claude Code OAuth token instead of an
+        # API key — flip the subscription scope so LLMProvider picks
+        # it up.
+        from core.anthropic_auth import subscription_auth_scope
+        with subscription_auth_scope():
+            return await planner.decompose_to_features(
+                goal=goal, stack_hints=list(stack), max_features=max_features,
+            )
+
+    try:
+        features = asyncio.run(_bootstrap())
+    except Exception as e:
+        console.print(f"[red]✗ Bootstrapper failed:[/red] {e}")
+        raise click.Abort()
+
+    if not features:
+        console.print("[yellow]Bootstrapper produced 0 features.[/yellow]")
+        return
+
+    # Render proposal first
+    console.print(f"\n[bold]Proposed backlog ({len(features)} features):[/bold]\n")
+    for idx, f in enumerate(features):
+        deps = f"deps={f.depends_on}" if f.depends_on else ""
+        verify = f"verify={f.verify_command!r}" if f.verify_command else ""
+        meta = " ".join(x for x in [deps, verify] if x)
+        console.print(
+            f"  [{idx}] [bold]{f.title}[/bold] "
+            f"[dim]P{f.priority} {f.category} {meta}[/dim]"
+        )
+        if f.description:
+            preview = f.description[:120].replace("\n", " ")
+            console.print(f"        [dim]{preview}…[/dim]")
+
+    if dry_run:
+        console.print("\n[yellow]Dry-run: nothing written to DB.[/yellow]")
+        return
+
+    # Write features in order, then resolve depends_on indices to ids
+    idx_to_id: dict[int, int] = {}
+    for idx, f in enumerate(features):
+        fid = create_feature(
+            project_id=project_id,
+            title=f.title,
+            description=f.description,
+            acceptance_criteria=f.acceptance_criteria,
+            priority=f.priority,
+            category=f.category if f.category in ("functional", "style")
+                     else "functional",
+            verify_command=f.verify_command,
+        )
+        idx_to_id[idx] = fid
+
+    for idx, f in enumerate(features):
+        for dep_idx in f.depends_on:
+            if dep_idx in idx_to_id and dep_idx != idx:
+                try:
+                    add_dependency(idx_to_id[idx], idx_to_id[dep_idx])
+                except Exception as e:
+                    logger.warning(f"failed to wire dep {idx}→{dep_idx}: {e}")
+
+    console.print(
+        f"\n[green]✓[/green] Wrote {len(features)} features to project "
+        f"[bold]{proj['name']}[/bold]. "
+        f"Inspect: [cyan]cognos forge feature list -p {project_id}[/cyan]"
+    )
+
+
+@forge.group("feature")
+def forge_feature():
+    """Manage features inside a project."""
+    pass
+
+
+@forge_feature.command("list")
+@click.option("--project", "-p", "project_id", type=int, required=True)
+def forge_feature_list(project_id: int):
+    """List all features for a project, ordered by priority."""
+    from planning.forge_models import init, list_features, get_project
+    init()
+    proj = get_project(project_id)
+    if not proj:
+        console.print(f"[red]✗ Project {project_id} not found.[/red]")
+        raise click.Abort()
+    rows = list_features(project_id)
+    if not rows:
+        console.print(f"[dim]No features yet for project "
+                      f"[bold]{proj['name']}[/bold]. "
+                      f"Try: cognos forge bootstrap \"...\" -p {project_id}[/dim]")
+        return
+    by_status = {"backlog": [], "in_progress": [], "completed": []}
+    for r in rows:
+        by_status.setdefault(r["status"], []).append(r)
+    console.print(f"\n[bold]{proj['name']}[/bold] kanban:\n")
+    for status in ("backlog", "in_progress", "completed"):
+        items = by_status.get(status, [])
+        console.print(f"  [bold]{status.upper()}[/bold] ({len(items)}):")
+        for r in items:
+            deps = f" deps={r['depends_on']}" if r['depends_on'] else ""
+            verify = f" verify={r['verify_command']!r}" if r['verify_command'] else ""
+            console.print(
+                f"    #{r['id']} P{r['priority']} [{r['category']}] "
+                f"{r['title']}[dim]{deps}{verify}[/dim]"
+            )
+
+
+@forge_feature.command("add")
+@click.option("--project", "-p", "project_id", type=int, required=True)
+@click.option("--title", required=True)
+@click.option("--description", default=None)
+@click.option("--criteria", "ac", default=None,
+              help="Acceptance criteria (free-form)")
+@click.option("--priority", default=0, type=int)
+@click.option("--category",
+              type=click.Choice(["functional", "style"]),
+              default="functional")
+@click.option("--verify", "verify_command", default=None)
+def forge_feature_add(project_id: int, title: str, description: str | None,
+                      ac: str | None, priority: int, category: str,
+                      verify_command: str | None):
+    """Manually add a feature to a project's backlog."""
+    from planning.forge_models import init, create_feature, get_project
+    init()
+    if not get_project(project_id):
+        console.print(f"[red]✗ Project {project_id} not found.[/red]")
+        raise click.Abort()
+    fid = create_feature(
+        project_id=project_id, title=title, description=description,
+        acceptance_criteria=ac, priority=priority, category=category,
+        verify_command=verify_command,
+    )
+    console.print(f"[green]✓[/green] Added feature [bold]#{fid}[/bold]: {title}")
+
+
+@forge_feature.command("dep")
+@click.argument("feature_id", type=int)
+@click.argument("depends_on_feature_id", type=int)
+def forge_feature_dep(feature_id: int, depends_on_feature_id: int):
+    """Wire a dependency: feature_id depends on depends_on_feature_id."""
+    from planning.forge_models import init, add_dependency
+    init()
+    try:
+        add_dependency(feature_id, depends_on_feature_id)
+    except ValueError as e:
+        console.print(f"[red]✗ {e}[/red]")
+        raise click.Abort()
+    console.print(
+        f"[green]✓[/green] {feature_id} now depends on {depends_on_feature_id}"
+    )
+
+
+@forge.command("start")
+@click.option("--project", "-p", "project_id", type=int, required=True)
+@click.option("--max-concurrent", default=None, type=int,
+              help="Override settings.forge.max_concurrent for this run")
+def forge_start(project_id: int, max_concurrent: int | None):
+    """Start the orchestrator: pick the next ready feature, run an agent.
+
+    Repeats until there are no ready features or the max-concurrent cap
+    is hit. Auto-continues after each feature finishes.
+    """
+    import asyncio
+    from planning.orchestrator import (
+        start_orchestrator, OrchestratorError, _state, subscribe_global,
+    )
+    setup_logging(verbose=False)
+
+    if max_concurrent is not None:
+        # Inject as an env-style override for this process. The
+        # orchestrator reads from settings on each call.
+        import os
+        os.environ["COGNOS_FORGE_MAX_CONCURRENT"] = str(max_concurrent)
+
+    async def _run():
+        # Kick off one start; auto-continue fills additional slots.
+        try:
+            res = await start_orchestrator(project_id)
+            console.print(
+                f"[green]▶[/green] session #{res['session_id']} on "
+                f"feature [bold]{res['feature_title']}[/bold] "
+                f"(#{res['feature_id']})"
+            )
+        except OrchestratorError as e:
+            console.print(f"[red]✗ {e}[/red]")
+            return
+
+        # Tail global events until no sessions remain running.
+        async for ev in subscribe_global():
+            t = ev.get("type")
+            if t == "log":
+                colour = {"error": "red", "action": "cyan",
+                          "test_result": "green"}.get(ev["message_type"], "")
+                pre = f"[{colour}]" if colour else ""
+                post = "[/]" if colour else ""
+                console.print(f"  {pre}[{ev['session_id']}] {ev['message']}{post}")
+            elif t == "status":
+                console.print(
+                    f"[bold]session {ev['session_id']}[/bold] → "
+                    f"{ev['session_status']}"
+                )
+            # When the running map empties, we're done.
+            if not _state().running:
+                console.print("[dim]all agents done[/dim]")
+                return
+
+    try:
+        asyncio.run(_run())
+    except KeyboardInterrupt:
+        console.print("[yellow]interrupted; in-flight sessions will be "
+                      "reaped on next start[/yellow]")
+
+
+@forge.command("stop")
+@click.option("--session", "session_id", type=int, default=None)
+@click.option("--project", "project_id", type=int, default=None)
+@click.option("--all", "stop_all", is_flag=True,
+              help="Stop all running sessions across all projects")
+def forge_stop(session_id: int | None, project_id: int | None, stop_all: bool):
+    """Stop a running session or sessions."""
+    from planning.orchestrator import (
+        stop_session, stop_all_for_project, _state,
+    )
+    if stop_all:
+        n = 0
+        for sid in list(_state().running.keys()):
+            stop_session(sid)
+            n += 1
+        console.print(f"[yellow]stopped {n} sessions[/yellow]")
+    elif project_id is not None:
+        n = stop_all_for_project(project_id)
+        console.print(
+            f"[yellow]stopped {n} sessions for project {project_id}[/yellow]"
+        )
+    elif session_id is not None:
+        if stop_session(session_id):
+            console.print(f"[yellow]stopped session {session_id}[/yellow]")
+        else:
+            console.print(f"[dim]session {session_id} was not live[/dim]")
+    else:
+        console.print(
+            "[red]✗ pass one of: --session ID | --project ID | --all[/red]"
+        )
+        raise click.Abort()
+
+
+@forge.command("status")
+@click.option("--project", "-p", "project_id", type=int, default=None)
+def forge_status(project_id: int | None):
+    """Print kanban state. Without --project, summarises every project."""
+    from planning.forge_models import init, list_projects
+    from planning.orchestrator import get_kanban_state, _state
+    init()
+    targets = ([project_id] if project_id is not None
+               else [p["id"] for p in list_projects()])
+    if not targets:
+        console.print("[dim]no projects yet[/dim]")
+        return
+    for pid in targets:
+        try:
+            state = get_kanban_state(pid)
+        except Exception as e:
+            console.print(f"[red]✗ {pid}: {e}[/red]")
+            continue
+        proj = state["project"]
+        feats = state["features"]
+        running = state["running_feature_ids"]
+        cap = state["max_concurrent"]
+        cols = {"backlog": [], "in_progress": [], "completed": []}
+        for f in feats:
+            cols.setdefault(f["status"], []).append(f)
+        console.print(
+            f"\n[bold cyan]{proj['name']}[/bold cyan] "
+            f"[dim]({proj['status']}, {len(running)}/{cap} agents live)[/dim]"
+        )
+        for s in ("backlog", "in_progress", "completed"):
+            items = cols.get(s, [])
+            console.print(f"  [bold]{s.upper()}[/bold] ({len(items)}):")
+            for f in items:
+                running_marker = "▶" if f["id"] in running else " "
+                deps = f" deps={f['depends_on']}" if f.get("depends_on") else ""
+                console.print(
+                    f"    {running_marker} #{f['id']} P{f['priority']} "
+                    f"{f['title']}[dim]{deps}[/dim]"
+                )
+
+
+@forge.command("attach")
+@click.argument("session_id", type=int)
+def forge_attach(session_id: int):
+    """Tail the live event stream for a session."""
+    import asyncio
+    from planning.orchestrator import subscribe_session
+    setup_logging(verbose=False)
+
+    async def _run():
+        async for ev in subscribe_session(session_id):
+            t = ev.get("type")
+            if t == "log":
+                replay = " [replay]" if ev.get("replay") else ""
+                colour = {"error": "red", "action": "cyan",
+                          "test_result": "green"}.get(ev.get("message_type", ""), "")
+                pre = f"[{colour}]" if colour else ""
+                post = "[/]" if colour else ""
+                console.print(f"{pre}{ev['message']}{post}{replay}")
+            elif t == "status":
+                console.print(
+                    f"[bold]→ {ev['session_status']}[/bold]"
+                )
+            elif t == "heartbeat":
+                pass
+    try:
+        asyncio.run(_run())
+    except KeyboardInterrupt:
+        pass
+
+
+@cli.group()
+def skills():
+    """Manage SKILL.md capability packs (lock, verify, list)."""
+
+
+@skills.command("list")
+def skills_list():
+    """List all loaded skills (TOC)."""
+    from core.skills import get_skills
+    reg = get_skills()
+    if not reg.skills:
+        console.print("[yellow]No skills installed.[/yellow]")
+        return
+    from rich.table import Table
+    t = Table(title=f"Skills ({len(reg.skills)})")
+    t.add_column("name"); t.add_column("source"); t.add_column("description")
+    for name in sorted(reg.skills):
+        s = reg.skills[name]
+        t.add_row(s.name, str(s.source_dir.name), s.description[:80])
+    console.print(t)
+
+
+@skills.command("lock")
+@click.option("--out", "out_path", default=None,
+              help="Lockfile path (defaults to data/skills.lock.json)")
+def skills_lock(out_path: str | None):
+    """Write data/skills.lock.json — content hash of every SKILL.md."""
+    from core.skills import lock_skills, get_skills, LOCKFILE_PATH
+    reg = get_skills()
+    target = Path(out_path) if out_path else LOCKFILE_PATH
+    payload = lock_skills(reg, lock_path=target)
+    console.print(
+        f"[green]locked[/] {payload['count']} skill(s) → {target}"
+    )
+
+
+@skills.command("verify")
+@click.option("--lock", "lock_path", default=None,
+              help="Lockfile path (defaults to data/skills.lock.json)")
+def skills_verify(lock_path: str | None):
+    """Compare live skills against the lockfile; non-zero exit on drift."""
+    from core.skills import verify_skills, LOCKFILE_PATH
+    target = Path(lock_path) if lock_path else LOCKFILE_PATH
+    rep = verify_skills(target)
+    if rep.get("error"):
+        console.print(f"[red]{rep['error']}[/red]")
+        raise click.exceptions.Exit(2)
+    if rep["ok"]:
+        console.print(
+            f"[green]✓ verified[/] {rep['unchanged']} skill(s) match {rep['lock_path']}"
+        )
+        return
+    console.print(f"[yellow]⚠ skill drift detected[/yellow]  (lock: {rep['lock_path']})")
+    if rep["missing"]:
+        console.print(f"  removed: {', '.join(rep['missing'])}")
+    if rep["added"]:
+        console.print(f"  added:   {', '.join(rep['added'])}")
+    if rep["changed"]:
+        console.print(f"  changed: {', '.join(rep['changed'])}")
+    raise click.exceptions.Exit(1)
+
+
+@skills.command("self")
+@click.option("--write/--no-write", default=True,
+              help="Write skills/forge/SKILL.md (default) or just print.")
+def skills_self(write: bool):
+    """Generate the auto-documenting SKILL.md for the forge command.
+
+    The skill teaches future LLMs how to drive ``cognos forge`` from
+    inside a chat session. Regenerated on demand so it stays in sync
+    with the actual CLI.
+    """
+    body = _render_forge_self_skill()
+    target = Path("/home/raveuk/cognos/skills/forge/SKILL.md")
+    if write:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(body)
+        console.print(f"[green]wrote[/] {target}  ({len(body)} bytes)")
+    else:
+        console.print(body)
+
+
+def _render_forge_self_skill() -> str:
+    """Self-documenting SKILL.md derived from this CLI."""
+    return """---
+name: forge
+description: Drive `cognos forge` — autonomous coding harness — from a chat. \
+Decompose a goal into a feature backlog, then run sessions until the project \
+is complete.
+---
+
+# Cognos Forge
+
+Forge is Cognos's autonomous coding harness, ported from LocalForge. It
+turns a natural-language goal into a kanban backlog, then runs an LLM
+agent on each feature with a watchdog and dependency-aware scheduling.
+
+## When to use this skill
+
+- The user wants to build something multi-step that can be split into
+  small features (each ≤ ~30 minutes of agent work).
+- They want hands-off execution: kanban runs in the background, the
+  user can watch progress in the web UI or via `cognos forge status`.
+
+## Surface area
+
+CLI (a click group):
+
+```
+cognos forge new <name> [--description ...] [--folder ...]
+cognos forge projects
+cognos forge bootstrap <goal> --project-id <id> [--stack python,fastapi]
+cognos forge feature list --project-id <id>
+cognos forge feature add --project-id <id> --title ... [--priority N]
+cognos forge feature dep <feature_id> <depends_on>
+cognos forge start --project-id <id> [--max-concurrent N]
+cognos forge stop  [--session-id N | --project-id N | --all]
+cognos forge status [--project-id <id>]
+cognos forge attach <session-id>     # tail logs live
+```
+
+REST + SSE (under `/forge`, served by `cognos serve`):
+
+```
+GET  /forge/projects
+POST /forge/projects                       {name, description?, folder_path?}
+GET  /forge/projects/{id}                  → kanban state
+POST /forge/projects/{id}/bootstrap        {goal, stack_hints[], max_features}
+POST /forge/projects/{id}/start
+POST /forge/projects/{id}/stop
+GET  /forge/sessions/{id}/events           SSE
+GET  /forge/events                         SSE (global)
+```
+
+Web UI: open the **Forge** tab in the sidebar at
+`http://<host>:8000/ui/`. The kanban board mirrors the CLI state.
+
+## Recommended flow
+
+1. `cognos forge new "<project name>"` — creates the row + sandbox dir.
+2. `cognos forge bootstrap "<one-paragraph goal>" --project-id <id>` —
+   the System-2 model decomposes into 5–15 features with dependencies.
+3. Review with `cognos forge feature list --project-id <id>`.
+4. `cognos forge start --project-id <id>` — orchestrator picks the
+   highest-priority backlog feature whose deps are completed and
+   spawns the agent.
+5. Watch via `cognos forge attach <session-id>` or the web UI.
+6. Auto-continue cascades A → B → C through the backlog.
+
+## Storage
+
+Everything in `data/cognos.db` (SQLAlchemy):
+- `forge_projects`, `forge_features`, `forge_feature_deps`
+- `forge_sessions`, `forge_logs`, `forge_chat_messages`, `forge_settings`
+
+## Caudate hook
+
+Each completed/failed session emits a feature-outcome sample to the
+neural observer (`nn/observer.py`). Caudate learns which models +
+prompts succeed at which feature shapes and biases future routing.
+
+## Don'ts
+
+- Don't bootstrap into an empty project root that already contains
+  unrelated files — Forge writes inside the project's `folder_path`.
+- Don't pick a System-2 model for `--system2` that lacks tool calling;
+  the bootstrapper needs structured JSON output.
+"""
+
+
+# LocalForge dev-script ports — every diagnostic, verify, setup, cleanup
+# helper from LocalForge's scripts/ ported to Python and registered as a
+# `cognos forge-tools <cmd>` click subcommand suite. Lazy-loaded so its
+# rich/sqlalchemy startup cost is paid only when invoked.
+try:
+    from bin.forge_scripts import cli as _forge_tools_cli
+    cli.add_command(_forge_tools_cli, name="forge-tools")
+except Exception as _e:  # pragma: no cover
+    logging.getLogger(__name__).debug(f"forge-tools registration skipped: {_e}")
+
+
+@cli.command("test-e2e")
+@click.option("--headed", is_flag=True, help="Run with the browser visible.")
+@click.option("--base-url", default="http://127.0.0.1:8000",
+              help="URL of a running cognos-serve.")
+@click.argument("playwright_args", nargs=-1)
+def test_e2e(headed: bool, base_url: str, playwright_args: tuple[str, ...]):
+    """Run the Playwright e2e suite for the Forge UI.
+
+    Requires Node + Playwright. Pass through extra Playwright args via:
+        cognos test-e2e -- --grep="celebration"
+    """
+    import os, subprocess
+    e2e_dir = Path("/home/raveuk/cognos/tests/e2e")
+    if not (e2e_dir / "node_modules").exists():
+        console.print("[yellow]Installing Playwright (first run)...[/]")
+        subprocess.check_call(["npm", "install"], cwd=str(e2e_dir))
+    args = ["npx", "playwright", "test"]
+    if headed:
+        args.append("--headed")
+    args.extend(playwright_args)
+    env = dict(os.environ)
+    env["COGNOS_BASE_URL"] = base_url
+    raise SystemExit(subprocess.call(args, cwd=str(e2e_dir), env=env))
+
+
+if __name__ == "__main__":
+    cli()