# Generation doctrine -- adopter app scaffolding rules

When you scaffold a new app (Phase V step 14) or wire backend
capabilities to the frontend, follow this hierarchy. It is the same
dogfooding pattern Forge itself runs on internally.

RULE G-DOC-1 -- NAC3 manifest is the default catalogue.
  Every backend tool the adopter app exposes (filesystem, network,
  external API, database, queue, scheduler, payment, email) lives
  as a verb in the app NAC3 manifest. Do NOT scaffold a flat REST
  router or a stand-alone MCP server as the FIRST surface; start
  with the manifest. Each verb declares: id (yujin.<scenario>.<verb>),
  role, action, schema, policy (unrestricted | confirm |
  approval-required | destructive | byok-required | scope-gated),
  side_effects ([none | dom | filesystem | network | process |
  external-api | git ...]).

RULE G-DOC-2 -- MCP is opt-in, never the default.
  Do NOT scaffold an MCP server unless the user explicitly asks for
  it (keywords: "MCP server", "expose via MCP", "Claude Desktop
  integration", "third-party agent tools"). When the user does ask,
  scaffold MCP BUT add a thin bridge layer that re-exports each MCP
  tool as a NAC3 verb in the app manifest with `mcp_bridge: { server,
  tool }`. The app frontend still sees ONE catalogue (NAC3).
  External agents that speak MCP get their flat surface; internal
  agents and the chat frontend stay manifest-only.

RULE G-DOC-3 -- Templates carry the example.
  Templates Forge writes include at least one backend verb (e.g.
  yujin.users.create or yujin.invoices.send) wired through the
  manifest as a working sample. NOT as a flat POST /api/users
  endpoint or an MCP tool definition.

RULE G-DOC-4 -- Why this is non-negotiable.
  Forge alpha.41 demonstrated that an LLM operating against a flat
  tool catalogue (Anthropic native tools or MCP) shows three failure
  modes that disappear under NAC3 manifest: hallucination (LLM
  claims action without an invoke), silent-fail (LLM ignores
  is_error=true), and model-size lock-in (catalog requires Opus;
  manifest works with Haiku/Flash). Adopter apps inherit these wins
  automatically when they build NAC3-first.

If the user pushes back ("I just want a REST endpoint" / "no NAC3
please, plain Express"), respect it BUT first explain the three
trade-offs above and offer the manifest as the default with a
one-line override. Decision logs go in PRD.
