fde-framework 0.1.1__tar.gz → 0.1.2__tar.gz

{fde_framework-0.1.1 → fde_framework-0.1.2}/CHANGELOG.md

@@ -5,6 +5,26 @@ the project is pre-release, so everything sits under 0.1.0 until the first tag.
 
 ## [Unreleased]
 
+## [0.1.2] — 2026-09-07
+
+A fresh-eyes usability round, every finding verified in a clean venv:
+
+- The hero quickstart runs verbatim: bare engagement names resolve
+  (`fde ask acme` finds `engagements/acme`), and `fde start` reads its
+  own statement through the prose reader, so the first minute shows
+  typed facts instead of "no facts recorded yet".
+- `fde --version`; interview questions show their legal values with the
+  question; gate remedies name their clearing commands; the baseline
+  refusal names the exact keys that satisfy it.
+- `fde implement` without an agent on PATH is a sentence with the fix,
+  never a traceback; `fde cost --price-per-seat` works without fleet
+  flags.
+- kb subcommands take `--registry` (with `--root` kept as an alias).
+- Every emitted project gets a front-door README; images are PNG so
+  they render on PyPI and mobile; the README gains a copy-paste full
+  lifecycle with the baseline YAML inline, and a Python API section
+  backed by the public `fde.registry.default_root()`.
+
 ## [0.1.1] — 2026-09-06
 
 - README images render everywhere: absolute URLs, because PyPI does not

{fde_framework-0.1.1 → fde_framework-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fde-framework
-Version: 0.1.1
+Version: 0.1.2
 Summary: A framework for Forward Deployed Engineers: from problem statement to a deployable AI project, every decision traced to a fact.
 Project-URL: Homepage, https://github.com/atulkapoor/fde-framework
 Project-URL: Repository, https://github.com/atulkapoor/fde-framework
@@ -36,8 +36,8 @@ Requires-Dist: anthropic>=0.40; extra == 'llm'
 Description-Content-Type: text/markdown
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/banner-dark.svg">
-  <img src="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/banner-light.svg" alt="fde — a framework for Forward Deployed Engineers" width="760">
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/banner-dark.png">
+  <img src="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/banner-light.png" alt="fde — a framework for Forward Deployed Engineers" width="760">
 </picture>
 
 # fde — a framework for Forward Deployed Engineers
@@ -49,6 +49,15 @@ Description-Content-Type: text/markdown
 ![Status](https://img.shields.io/badge/status-alpha-orange)
 [![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
 
+<p>
+  <a href="#install">Install</a> ·
+  <a href="#try-it-in-two-minutes">Quickstart</a> ·
+  <a href="ARCHITECTURE.md">Architecture</a> ·
+  <a href="examples/invoice-extraction/">Worked example</a> ·
+  <a href="CONTRIBUTING.md">Contributing</a> ·
+  <a href="https://pypi.org/project/fde-framework/">PyPI</a>
+</p>
+
 **fde** is an open-source framework for Forward Deployed Engineers: it takes a
 client engagement from a problem statement to a runnable, deployable AI
 project — with every decision traced to a fact, and every fact traced to a
@@ -68,7 +77,7 @@ fde architect acme               # the design, with cited rationale
 fde build acme --out project     # code + evals + deploy assets + runbook
 ```
 
-<img src="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/demo.svg" alt="fde in a terminal: a paragraph becomes typed facts, an architecture with a fingerprint, and a build that refuses until the hard gate passes" width="780">
+<img src="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/demo.png" alt="fde in a terminal: a paragraph becomes typed facts, an architecture with a fingerprint, and a build that refuses until the hard gate passes" width="780">
 
 *That refusal at the end is the product working: no baseline, no verified data
 access — no build. The remedies ship with every gate.*
@@ -232,18 +241,18 @@ refuses by name and says exactly what to install.
 ## Try it
 
 ```bash
-.venv/bin/fde start acme --statement "Extract fields from supplier invoices."
-.venv/bin/fde ask engagements/acme --role admin      # role-scoped interview
-.venv/bin/fde status engagements/acme                # gates, gaps, disagreements
-.venv/bin/fde architect engagements/acme             # the design, with rationale
-.venv/bin/fde build engagements/acme --out project   # refuses until gates clear
-
-.venv/bin/fde scan engagements/acme                  # what this hardware runs
-.venv/bin/fde cost --requests-per-day 500000 --model-b 70   # dated fleet sizing
-
-.venv/bin/fde kb validate --root framework   # parse and cross-link the registry
-.venv/bin/fde kb gaps     --root framework   # what the corpus is missing
-.venv/bin/fde kb sweep    --root framework   # profiles no approach can serve
+fde start acme --statement "Extract fields from supplier invoices."
+fde ask engagements/acme --role admin      # role-scoped interview
+fde status engagements/acme                # gates, gaps, disagreements
+fde architect engagements/acme             # the design, with rationale
+fde build engagements/acme --out project   # refuses until gates clear
+
+fde scan engagements/acme                  # what this hardware runs
+fde cost --requests-per-day 500000 --model-b 70   # dated fleet sizing
+
+fde kb validate   # parse and cross-link the registry
+fde kb gaps     --root framework   # what the corpus is missing
+fde kb sweep    --root framework   # profiles no approach can serve
 .venv/bin/pytest -q
 ```
 
@@ -276,6 +285,66 @@ project/
 └── COMPLIANCE.md         # jurisdiction obligations, when a locale pack was applied
 ```
 
+## The full lifecycle, copy-paste
+
+Everything below runs from an empty directory after `pip install fde-framework`:
+
+```bash
+fde start acme --statement "Extract fields from scanned supplier invoices; \
+data cannot leave; 200,000 documents, 8,000 verified; a person is waiting."
+# plays back the typed facts it read, and the three questions worth asking next
+
+fde ask acme --role eval_owner       # answer what discovery still needs
+fde status acme                      # facts by scope, gates, % settled
+
+cat > baseline.yaml <<'YAML'
+volume: {value: 20000, unit: docs/month, definition: invoices received by AP}
+cycle_time_per_unit_seconds: {value: 300, unit: s, definition: arrival to posted}
+labour_hours_per_week: {value: 35, unit: h/week, definition: AP team keying time}
+rework_rate: {value: 0.1, unit: ratio, definition: entries corrected after post}
+exception_rate: {value: 0.07, unit: ratio, definition: routed to a human queue}
+error_rate: {value: 0.04, unit: ratio, definition: wrong amount or vendor posted}
+business_metric: {value: 9, unit: days, definition: mean days payable outstanding}
+sampled: {n: 40, method: random invoices across two months}
+YAML
+fde baseline acme --file baseline.yaml
+fde data-access acme --note "read replica returned 14 real rows"
+fde security-review acme --note "client infosec walked the data paths"
+fde ask acme --role eval_owner       # or: fde waive acme client_readiness --reason "..."
+
+fde build acme --out project         # refuses until the gates truly pass
+python project/evals/harness.py      # red until implemented -- that's the exam
+fde implement project                # drive a coding agent until it's green
+```
+
+## Python API
+
+The CLI is a thin layer; everything is importable. The registry loads from the
+installed wheel, so this runs anywhere:
+
+```python
+from fde.architect import architect
+from fde.intake.prose import parse_prose
+from fde.models.profile import Profile
+from fde.registry import default_root, load_registry
+
+registry = load_registry(default_root())
+
+profile = Profile()
+profile.ingest(parse_prose(
+    "500,000 scanned invoices; data cannot leave; 10,000 verified; "
+    "a person is waiting; structured records out.", registry))
+
+design = architect(profile, registry)
+print(design.topology)                    # customer-vpc
+for component, decision in sorted(design.decisions.items()):
+    if decision.approach:
+        print(component, decision.approach, decision.rationale)
+```
+
+Every decision object carries its rationale and its rejected alternatives —
+the same receipts the emitted `ARCHITECTURE.md` prints.
+
 ## Common commands
 
 | | |
@@ -429,7 +498,7 @@ The registry is the shared asset; engagements are private working state.
   deliberately waits for a corpus of measured retrospectives rather than
   pretending a handful is evidence.
 - **More locale packs and stacks** — both are data; contributions enter
-  against [CONTRIBUTING.md](CONTRIBUTING.md)'s contract.
+  against [CONTRIBUTING.md](CONTRIBUTING.md)'s contract (and the [code of conduct](CODE_OF_CONDUCT.md)).
 - **Language, channel, and device axes** — six of twenty industry test
   statements named regional languages, low bandwidth, or basic devices;
   the honest wiring (per-language evaluation, SMS/IVR serving approaches,

{fde_framework-0.1.1 → fde_framework-0.1.2}/README.md

@@ -1,6 +1,6 @@
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/banner-dark.svg">
-  <img src="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/banner-light.svg" alt="fde — a framework for Forward Deployed Engineers" width="760">
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/banner-dark.png">
+  <img src="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/banner-light.png" alt="fde — a framework for Forward Deployed Engineers" width="760">
 </picture>
 
 # fde — a framework for Forward Deployed Engineers
@@ -12,6 +12,15 @@
 ![Status](https://img.shields.io/badge/status-alpha-orange)
 [![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
 
+<p>
+  <a href="#install">Install</a> ·
+  <a href="#try-it-in-two-minutes">Quickstart</a> ·
+  <a href="ARCHITECTURE.md">Architecture</a> ·
+  <a href="examples/invoice-extraction/">Worked example</a> ·
+  <a href="CONTRIBUTING.md">Contributing</a> ·
+  <a href="https://pypi.org/project/fde-framework/">PyPI</a>
+</p>
+
 **fde** is an open-source framework for Forward Deployed Engineers: it takes a
 client engagement from a problem statement to a runnable, deployable AI
 project — with every decision traced to a fact, and every fact traced to a
@@ -31,7 +40,7 @@ fde architect acme               # the design, with cited rationale
 fde build acme --out project     # code + evals + deploy assets + runbook
 ```
 
-<img src="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/demo.svg" alt="fde in a terminal: a paragraph becomes typed facts, an architecture with a fingerprint, and a build that refuses until the hard gate passes" width="780">
+<img src="https://raw.githubusercontent.com/atulkapoor/fde-framework/main/assets/demo.png" alt="fde in a terminal: a paragraph becomes typed facts, an architecture with a fingerprint, and a build that refuses until the hard gate passes" width="780">
 
 *That refusal at the end is the product working: no baseline, no verified data
 access — no build. The remedies ship with every gate.*
@@ -195,18 +204,18 @@ refuses by name and says exactly what to install.
 ## Try it
 
 ```bash
-.venv/bin/fde start acme --statement "Extract fields from supplier invoices."
-.venv/bin/fde ask engagements/acme --role admin      # role-scoped interview
-.venv/bin/fde status engagements/acme                # gates, gaps, disagreements
-.venv/bin/fde architect engagements/acme             # the design, with rationale
-.venv/bin/fde build engagements/acme --out project   # refuses until gates clear
-
-.venv/bin/fde scan engagements/acme                  # what this hardware runs
-.venv/bin/fde cost --requests-per-day 500000 --model-b 70   # dated fleet sizing
-
-.venv/bin/fde kb validate --root framework   # parse and cross-link the registry
-.venv/bin/fde kb gaps     --root framework   # what the corpus is missing
-.venv/bin/fde kb sweep    --root framework   # profiles no approach can serve
+fde start acme --statement "Extract fields from supplier invoices."
+fde ask engagements/acme --role admin      # role-scoped interview
+fde status engagements/acme                # gates, gaps, disagreements
+fde architect engagements/acme             # the design, with rationale
+fde build engagements/acme --out project   # refuses until gates clear
+
+fde scan engagements/acme                  # what this hardware runs
+fde cost --requests-per-day 500000 --model-b 70   # dated fleet sizing
+
+fde kb validate   # parse and cross-link the registry
+fde kb gaps     --root framework   # what the corpus is missing
+fde kb sweep    --root framework   # profiles no approach can serve
 .venv/bin/pytest -q
 ```
 
@@ -239,6 +248,66 @@ project/
 └── COMPLIANCE.md         # jurisdiction obligations, when a locale pack was applied
 ```
 
+## The full lifecycle, copy-paste
+
+Everything below runs from an empty directory after `pip install fde-framework`:
+
+```bash
+fde start acme --statement "Extract fields from scanned supplier invoices; \
+data cannot leave; 200,000 documents, 8,000 verified; a person is waiting."
+# plays back the typed facts it read, and the three questions worth asking next
+
+fde ask acme --role eval_owner       # answer what discovery still needs
+fde status acme                      # facts by scope, gates, % settled
+
+cat > baseline.yaml <<'YAML'
+volume: {value: 20000, unit: docs/month, definition: invoices received by AP}
+cycle_time_per_unit_seconds: {value: 300, unit: s, definition: arrival to posted}
+labour_hours_per_week: {value: 35, unit: h/week, definition: AP team keying time}
+rework_rate: {value: 0.1, unit: ratio, definition: entries corrected after post}
+exception_rate: {value: 0.07, unit: ratio, definition: routed to a human queue}
+error_rate: {value: 0.04, unit: ratio, definition: wrong amount or vendor posted}
+business_metric: {value: 9, unit: days, definition: mean days payable outstanding}
+sampled: {n: 40, method: random invoices across two months}
+YAML
+fde baseline acme --file baseline.yaml
+fde data-access acme --note "read replica returned 14 real rows"
+fde security-review acme --note "client infosec walked the data paths"
+fde ask acme --role eval_owner       # or: fde waive acme client_readiness --reason "..."
+
+fde build acme --out project         # refuses until the gates truly pass
+python project/evals/harness.py      # red until implemented -- that's the exam
+fde implement project                # drive a coding agent until it's green
+```
+
+## Python API
+
+The CLI is a thin layer; everything is importable. The registry loads from the
+installed wheel, so this runs anywhere:
+
+```python
+from fde.architect import architect
+from fde.intake.prose import parse_prose
+from fde.models.profile import Profile
+from fde.registry import default_root, load_registry
+
+registry = load_registry(default_root())
+
+profile = Profile()
+profile.ingest(parse_prose(
+    "500,000 scanned invoices; data cannot leave; 10,000 verified; "
+    "a person is waiting; structured records out.", registry))
+
+design = architect(profile, registry)
+print(design.topology)                    # customer-vpc
+for component, decision in sorted(design.decisions.items()):
+    if decision.approach:
+        print(component, decision.approach, decision.rationale)
+```
+
+Every decision object carries its rationale and its rejected alternatives —
+the same receipts the emitted `ARCHITECTURE.md` prints.
+
 ## Common commands
 
 | | |
@@ -392,7 +461,7 @@ The registry is the shared asset; engagements are private working state.
   deliberately waits for a corpus of measured retrospectives rather than
   pretending a handful is evidence.
 - **More locale packs and stacks** — both are data; contributions enter
-  against [CONTRIBUTING.md](CONTRIBUTING.md)'s contract.
+  against [CONTRIBUTING.md](CONTRIBUTING.md)'s contract (and the [code of conduct](CODE_OF_CONDUCT.md)).
 - **Language, channel, and device axes** — six of twenty industry test
   statements named regional languages, low bandwidth, or basic devices;
   the honest wiring (per-language evaluation, SMS/IVR serving approaches,

{fde_framework-0.1.1 → fde_framework-0.1.2}/pyproject.toml

@@ -2,7 +2,7 @@
 # Distribution name matches the repository and stays unique on any index;
 # the import package and the CLI command remain the short `fde`.
 name = "fde-framework"
-version = "0.1.1"
+version = "0.1.2"
 description = "A framework for Forward Deployed Engineers: from problem statement to a deployable AI project, every decision traced to a fact."
 readme = "README.md"
 license = {text = "Apache-2.0"}

{fde_framework-0.1.1 → fde_framework-0.1.2}/src/fde/cli.py

@@ -47,7 +47,7 @@ from fde.models.fact import Fact
 from fde.models.profile import Profile
 from fde.models.respondent import Respondent, Role
 from fde.predicate import PredicateError, holds
-from fde.registry import KINDS, RegistryError, is_empty, load_registry
+from fde.registry import KINDS, RegistryError, default_root, is_empty, load_registry
 from fde.scan import (
     GPU,
     Hardware,
@@ -60,32 +60,30 @@ from fde.scan import (
 from fde.space import Contradiction, Space
 
 app = typer.Typer(help="Take an engagement from problem statement to a runnable project.")
-kb = typer.Typer(help="Inspect the knowledge base in framework/.")
-app.add_typer(kb, name="kb")
-
-def _default_registry_root() -> Path:
-    """A checkout's ./framework when present, else the copy in the wheel.
 
-    Local first, always: a contributor editing the corpus must see their
-    edits, not the packaged snapshot. The packaged copy is what makes
-    `pip install fde-framework` a working tool rather than a tool with no
-    knowledge base.
-    """
-    local = Path("framework")
-    if local.is_dir():
-        return local
-    try:
-        from importlib.resources import files
 
-        packaged = Path(str(files("fde") / "framework"))
-        if packaged.is_dir():
-            return packaged
-    except (ImportError, TypeError):
-        pass
-    return local
+@app.callback(invoke_without_command=True)
+def _main(
+    ctx: typer.Context,
+    version: Annotated[bool, typer.Option(
+        "--version", help="Print the version and exit."
+    )] = False,
+) -> None:
+    if version:
+        from importlib.metadata import version as pkg_version
 
+        try:
+            typer.echo(f"fde-framework {pkg_version('fde-framework')}")
+        except Exception:  # noqa: BLE001 - source checkout without install metadata
+            typer.echo("fde-framework (source checkout)")
+        raise typer.Exit(0)
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit(0)
+kb = typer.Typer(help="Inspect the knowledge base in framework/.")
+app.add_typer(kb, name="kb")
 
-DEFAULT_ROOT = _default_registry_root()
+DEFAULT_ROOT = default_root()
 
 # What `fde retro` writes, and the only shape ingest will treat as a filename.
 CASE_ID = re.compile(r"case-[0-9a-f]{6,32}")
@@ -93,7 +91,10 @@ CASE_ID = re.compile(r"case-[0-9a-f]{6,32}")
 
 @kb.command("validate")
 def kb_validate(
-    root: Annotated[Path, typer.Option(help="Registry directory.")] = DEFAULT_ROOT,
+    root: Annotated[Path, typer.Option(
+        "--registry", "--root",
+        help="Registry directory (--root kept as an alias).",
+    )] = DEFAULT_ROOT,
     lenient: Annotated[
         bool, typer.Option(help="Report dangling links without failing.")
     ] = False,
@@ -145,6 +146,30 @@ def start(
     typer.echo("  artifacts/  drop specs, schemas and sample pairs here")
     if not statement:
         typer.echo("\nNo statement yet. Add prose later, or start answering questions.")
+        return
+
+    # The statement is prose; read it like prose. Handing the tool a
+    # sentence and being told "no facts recorded yet" one command later
+    # made the first minute feel broken -- the reader was just never asked.
+    try:
+        registry = load_registry(DEFAULT_ROOT)
+    except RegistryError:
+        return
+    facts = parse_prose(statement, registry, source="statement")
+    if facts:
+        typer.echo("")
+        typer.echo(restate(facts, registry))
+        session_id = _next_session_id(engagement, "frame")
+        briefs = engagement.artifacts_dir / "briefs"
+        briefs.mkdir(parents=True, exist_ok=True)
+        (briefs / f"{session_id}.txt").write_text(statement)
+        engagement.append(
+            Session(
+                session_id=session_id,
+                respondent=Respondent(role=Role.SYSTEM),
+                facts=facts,
+            )
+        )
 
 
 @app.command("status")
@@ -642,9 +667,13 @@ def _put(dimension, question):
     End of input ends the interview rather than aborting it: whatever was
     gathered up to that point is still worth recording.
     """
+    hint = ""
+    if getattr(dimension, "values", None):
+        hint = f"  [{' / '.join(dimension.values)}]"
     while True:
         try:
-            reply = typer.prompt(f"\n{question.asks}", default="", show_default=False)
+            reply = typer.prompt(f"\n{question.asks}{hint}", default="",
+                                 show_default=False)
         except (EOFError, typer.Abort):
             return None
         answer = parse_answer(dimension, reply)
@@ -715,6 +744,12 @@ def _engagement(root: Path):
     file is a one-line explanation, never a traceback -- a stack trace at a
     client site reads as the tool being broken rather than the input.
     """
+    root = Path(root)
+    # `fde ask acme` after `fde start acme` should just work: start put it
+    # in engagements/acme, and making every later command spell that out
+    # cost every new user their first two minutes.
+    if not (root / "facts").is_dir() and (Path("engagements") / root).is_dir():
+        root = Path("engagements") / root
     try:
         engagement = load_engagement(root)
         # Read once here so a hand-edited gates.yaml fails as a sentence
@@ -1670,7 +1705,7 @@ def implement_cmd(
     reported if the agent touches them. Every round lands in
     ops/implement-log.md.
     """
-    from fde.implement import run_loop
+    from fde.implement import AgentMissing, run_loop
 
     project = Path(project)
     if not (project / "evals").is_dir() or not (project / "app").is_dir():
@@ -1680,8 +1715,12 @@ def implement_cmd(
         )
         raise typer.Exit(1)
 
-    report = run_loop(project, agent_cmd=agent_cmd, max_rounds=max_rounds,
-                      check=check, holdout=holdout)
+    try:
+        report = run_loop(project, agent_cmd=agent_cmd, max_rounds=max_rounds,
+                          check=check, holdout=holdout)
+    except AgentMissing as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
     (project / "ops").mkdir(exist_ok=True)
     (project / "ops" / "implement-log.md").write_text(report.log())
 
@@ -1811,6 +1850,13 @@ def cost_cmd(
             typer.echo(f"arrival_rate from the engagement: {requests_per_day:,}/day")
         if human_waiting is None and values.get("human_waiting") is not None:
             human_waiting = values["human_waiting"] != "no"
+    if requests_per_day is None and price_per_seat is not None:
+        # Seat economics needs workflows, not fleet volume: the README's own
+        # one-liner failed for demanding a number the check never uses.
+        requests_per_day = int(workflows_per_day)
+        skip_fleet = True
+    else:
+        skip_fleet = False
     if requests_per_day is None:
         typer.echo(
             "no volume to size for -- pass --requests-per-day, or --root an "
@@ -1820,31 +1866,35 @@ def cost_cmd(
     if human_waiting is None:
         human_waiting = True
 
-    plan = size_for(requests_per_day, params_b, today=stamp)
-    comparison = compare_hosting(
-        requests_per_day, params_b, human_waiting=human_waiting, today=stamp
-    )
+    if skip_fleet:
+        plan = None
+    else:
+        plan = size_for(requests_per_day, params_b, today=stamp)
+    if plan is not None:
+        comparison = compare_hosting(
+            requests_per_day, params_b, human_waiting=human_waiting, today=stamp
+        )
 
-    typer.echo(
-        f"{params_b:g}B at {requests_per_day:,}/day"
-        f"{' (interactive)' if human_waiting else ' (batch, nobody waiting)'}\n"
-    )
-    typer.echo(f"  naive:  {plan['naive_replicas']} replica(s)")
-    typer.echo(
-        f"  real:   {plan['replicas']} replica(s) x {plan['gpus_per_replica']} "
-        f"card(s) = {plan['gpus']} cards"
-    )
-    for name, why in plan["factors"].items():
-        typer.echo(f"      {name}: {why}")
+        typer.echo(
+            f"{params_b:g}B at {requests_per_day:,}/day"
+            f"{' (interactive)' if human_waiting else ' (batch, nobody waiting)'}\n"
+        )
+        typer.echo(f"  naive:  {plan['naive_replicas']} replica(s)")
+        typer.echo(
+            f"  real:   {plan['replicas']} replica(s) x {plan['gpus_per_replica']} "
+            f"card(s) = {plan['gpus']} cards"
+        )
+        for name, why in plan["factors"].items():
+            typer.echo(f"      {name}: {why}")
 
-    typer.echo(
-        f"\n  self-hosted  ${comparison['self_hosted_monthly']:,.0f}/mo\n"
-        f"  managed      ${comparison['managed_monthly']:,.0f}/mo\n"
-        f"  -> {comparison['recommendation']}: {comparison['why']}"
-    )
-    typer.echo(
-        f"\n  as of {plan['as_of']} -- {plan['rederive']}"
-    )
+        typer.echo(
+            f"\n  self-hosted  ${comparison['self_hosted_monthly']:,.0f}/mo\n"
+            f"  managed      ${comparison['managed_monthly']:,.0f}/mo\n"
+            f"  -> {comparison['recommendation']}: {comparison['why']}"
+        )
+        typer.echo(
+            f"\n  as of {plan['as_of']} -- {plan['rederive']}"
+        )
 
     if price_per_seat is not None:
         from fde.costing import unit_economics
@@ -1872,7 +1922,10 @@ def cost_cmd(
 @kb.command("ingest-case")
 def kb_ingest_case(
     case_file: Annotated[Path, typer.Argument(help="A case.json from `fde retro`.")],
-    root: Annotated[Path, typer.Option(help="Registry directory.")] = DEFAULT_ROOT,
+    root: Annotated[Path, typer.Option(
+        "--registry", "--root",
+        help="Registry directory (--root kept as an alias).",
+    )] = DEFAULT_ROOT,
 ) -> None:
     """Bring a captured case into the corpus -- as pending, never as reviewed.
 
@@ -2048,7 +2101,10 @@ def kb_suggest(
 
 @kb.command("sweep")
 def kb_sweep(
-    root: Annotated[Path, typer.Option(help="Registry directory.")] = DEFAULT_ROOT,
+    root: Annotated[Path, typer.Option(
+        "--registry", "--root",
+        help="Registry directory (--root kept as an alias).",
+    )] = DEFAULT_ROOT,
     samples: Annotated[int, typer.Option(help="Fully specified profiles to try.")] = 300,
     seed: Annotated[int, typer.Option(help="Deterministic sampling seed.")] = 0,
 ) -> None:
@@ -2086,7 +2142,10 @@ def kb_sweep(
 
 @kb.command("gaps")
 def kb_gaps(
-    root: Annotated[Path, typer.Option(help="Registry directory.")] = DEFAULT_ROOT,
+    root: Annotated[Path, typer.Option(
+        "--registry", "--root",
+        help="Registry directory (--root kept as an alias).",
+    )] = DEFAULT_ROOT,
 ) -> None:
     """Report what the corpus is missing. Work items, not errors -- always exits 0."""
     try:

{fde_framework-0.1.1 → fde_framework-0.1.2}/src/fde/emit.py

@@ -216,6 +216,40 @@ def _write_package(architecture: Architecture, out: Path) -> None:
         f"Regenerating from the same profile produces the same files, so a diff\n"
         f'between two builds means a decision changed.\n"""\n'
     )
+    (out / "README.md").write_text(
+        f"# {architecture.topology} deployment -- generated by fde-framework\n"
+        "\n"
+        "This project was emitted from an engagement profile. Every decision\n"
+        "in it is traced in [ARCHITECTURE.md](ARCHITECTURE.md); every risk\n"
+        "accepted along the way is in [RISKS.md](RISKS.md).\n"
+        "\n"
+        "## Run the evaluation\n"
+        "\n"
+        "```bash\n"
+        "python evals/harness.py --min-score 0.9\n"
+        "```\n"
+        "\n"
+        "It fails until the pipeline is implemented end to end -- that is the\n"
+        "point. The scaffolded components under `app/components/` carry their\n"
+        "contracts; implement them by hand, or drive a coding agent against\n"
+        "the harness with `fde implement .` (the evals, the boundary and the\n"
+        "decision documents are fenced -- an agent that edits them is caught\n"
+        "and reverted).\n"
+        "\n"
+        "## The pieces\n"
+        "\n"
+        "| Path | What it is |\n"
+        "|---|---|\n"
+        "| `app/pipeline.py` | The run order: payload steps, approval gates, critics |\n"
+        "| `app/contract.py` | RefusedInput -- forbidden input is refused, never guessed at |\n"
+        "| `evals/` | Golden / edge / adversarial sets from the client's "
+        "own pairs, plus the acceptance protocol |\n"
+        "| `deploy/` | The substrate this profile earned, and how to tear it down |\n"
+        "| `ops/` | Runbook keyed to the failure taxonomy, SLOs, rollback |\n"
+        "\n"
+        "Regenerating from the same facts reproduces this project byte for\n"
+        "byte; a diff between two builds means a decision changed.\n"
+    )
     (out / "app" / "components" / "__init__.py").write_text("")
     (out / "app" / "contract.py").write_text(
         '"""The one contract every step shares: forbidden input is refused.\n'