Add FAQ to docs/topics

[bar-capsule]

Summary

Adds a new documentation page (docs/topics/faq.md) covering ACS positioning, scope, paradigm support, deployment, operations, and roadmap.

The FAQ answers questions from four audiences (enterprise security teams, framework implementers, researchers, press) on one page, sourced from the merged v0.1.0 spec. No normative claims beyond what docs/spec/conformance.md defines.

What lands

• docs/topics/faq.md — new file, ~25 Q&As across six sections (About ACS / Scope and boundaries / For framework implementers / For enterprises / For researchers and paradigm authors / Versioning and roadmap)
• mkdocs.yml — one-line nav addition adding the FAQ under the existing Topics group
• Diagrams are ASCII box art in fenced code blocks (architecture, decision-failure flow, profile composition, paradigm-to-wire mapping). No mermaid plugin required.

Test plan

• mkdocs serve renders the new page under Topics → FAQ
• ASCII diagrams render correctly in MkDocs Material, GitHub, and VSCode markdown preview
• No broken internal links

🤖 Generated with Claude Code

[rocklambros]

Merge-order note: hold this until #21 lands, and reconcile the FAQ to the slimmed floor before merging. Right now faq.md is half-aligned, so it contradicts whichever conformance.md it sits next to.

• faq.md:124 already says the subagent hooks are mandatory. That matches Slim ACS-Core: relax MODIFY, system/ping, and wrapped MCP to SHOULD #21 but contradicts the conformance.md on main today (which still lists them as SHOULD). So merging this before Slim ACS-Core: relax MODIFY, system/ping, and wrapped MCP to SHOULD #21 puts a contradiction on main.
• faq.md:125, :130, :131 still describe the old floor: "Five dispositions" with required fields, system/ping as Core, Wrapped MCP as Core. Slim ACS-Core: relax MODIFY, system/ping, and wrapped MCP to SHOULD #21 turns all three into SHOULD (four MUST dispositions with MODIFY as SHOULD; ping SHOULD; MCP SHOULD). So even after Slim ACS-Core: relax MODIFY, system/ping, and wrapped MCP to SHOULD #21 lands, those three lines contradict the floor unless they're updated. The box diagram near the top (around :19 and :28) says the same thing and needs the same touch.

Fix is small: update those FAQ lines to match #21's floor, then merge after #21. No git conflict with #21 (different files), so this is sequencing for consistency, not a rebase.

cc @afogel since you approved this. The catch before merge is the FAQ reconcile plus ordering after #21. @bar-capsule

[rocklambros]

@bar-capsule

TL;DR - Let's sort out PRs 21 and 22 and then readdress this.

Details:

The FAQ is genuinely useful and I want it merged. It's also going to be the most-read page in the docs, which is exactly why I want to slow down on a few things before it lands.

The short version: this page is currently more normative than it looks, it contradicts the spec on three items, and one section defines the project's governance in a way the repo doesn't back up.

It contradicts #21 on three of the four items #21 changes

Item 3 in the ten-component list at line 124 already carries #21's subagent language nearly word for word, including the "satisfy this vacuously" rationale. So this page was written against a partially-applied #21. The other three didn't come along:

• Line 125 says "Five dispositions." Slim ACS-Core: relax MODIFY, system/ping, and wrapped MCP to SHOULD #21's line 20 makes it four MUST plus MODIFY as SHOULD.
• Line 130 lists system/ping as a mandatory component. Slim ACS-Core: relax MODIFY, system/ping, and wrapped MCP to SHOULD #21's line 25 makes it SHOULD, MAY be omitted.
• Line 131 lists Wrapped MCP as mandatory. Slim ACS-Core: relax MODIFY, system/ping, and wrapped MCP to SHOULD #21's line 26 makes it SHOULD, MAY be omitted.

The pillar diagram up at lines 19 to 28 repeats both, listing "5 dispositions" and "system/ping liveness" as baseline.

Partial sync is worse than none, and that's not a dig. Unsynchronized docs get caught in review, because the mismatch is obvious. A doc that matches on one item and diverges on three passes review, because a reviewer who sees the subagent paragraph lining up reasonably infers the rest was checked too. I nearly did that myself.

Easiest path is to gate this on #21's final text and rebase. Better long-term, replace the numbered restatement with a link, so ACS-Core is stated in exactly one place in the repo.

By the project's own rule, this page is normative

This is the one I'd push hardest on, because I don't think it's the intent.

SPEC_REVIEW_PRINCIPLES.md:60 says "Spec text is normative unless it says otherwise. Mark informative sections explicitly with 'This section is non-normative'." Line 62 adds that "Non-normative prose carries no RFC 2119 keywords."

I grepped: faq.md has three capitalized RFC 2119 keywords and zero non-normative markers. So under the project's own rule this is normative text, and it's normative text that disagrees with conformance.md on three items with no precedence statement anywhere in the repo.

Practically, this page wins. It sits higher in the nav than Conformance Profiles, it's far more readable, and it's the thing a procurement team will quote back at a vendor. Two definitions of the same conformance claim, and the readable one governs by default.

Cheap fix: a line at the top saying this page is non-normative and that docs/spec/conformance.md governs on conflict, plus lowercasing the RFC 2119 keywords at lines 127, 129, and 133.

The checkpoint count overstates the control surface

Line 44 says "ACS defines 22 such checkpoints across the agent lifecycle. The Guardian decides each one independently," right after line 40 defines a checkpoint as something that "asks one question (should this proceed?), gets one decision."

Six of those 22 aren't decision-eligible. hooks.md marks postCompact, subagentStop, skillUnload, turnEnd, and sessionEnd as audit-only, and specification.md:366 says Guardians "MUST always return decision: allow for system/ping regardless of policy." So a reader sizing their policy work, latency budget, and audit expectations against 22 independently-decided control points is sizing against roughly 13.

The airport-security analogy at line 42 reinforces the wrong model, since the whole point of that image is that every checkpoint can stop you.

There's also a count inconsistency worth cleaning up while you're there. This page says 22 at line 44 and 306, 19 at line 18, docs/acs.md:11 says "16 native lifecycle hooks," and specification.md:83-101 lists 16. Those are probably three different denominators (all schemas, steps/* only, and something else), but a reader can't tell which is which.

I'd restate it as something like "19 lifecycle hooks, of which 13 are decision-eligible control points and the rest are audit-only records," and drop system/ping and agbom/* from the checkpoint count.

Two claims I think overshoot

Line 65 describes the Guardian as "a policy authority outside the LLM's context that prompt injection cannot influence." But specification.md:347 requires that the Guardian's own Agent layer "MUST treat untrusted data as data, not instructions" and that "Untrusted fields MUST be wrapped/quoted." That requirement only exists because the Guardian's LLM layer ingests attacker-reachable content. A deployment running that optional layer has an injection-reachable Guardian.

Line 108 says "What ACS prevents is the agent acting on injected reasoning without being detected." Line 206 of the same page says that if the Guardian times out or errors, "the action proceeds and the bypass is recorded as an audit event." So an attacker who can DoS the Guardian defeats the line-108 guarantee, and the page says so 98 lines later.

What makes this awkward is that the FAQ is unusually honest elsewhere. Line 106's "Does ACS prevent prompt injection? No, and no runtime mechanism can" is better than most vendor docs manage, and line 241's "mechanism-to-control, not promise-to-eliminate" is exactly right. That candor is what buys unearned trust in the paragraphs that overreach, and 65 and 108 are the two that will get quoted back at the project after an incident.

Qualifying line 65 with the §12.2 caveat and moving the fail-open disclosure up into the "what is a hook" answer would fix both.

Separately, the overhead numbers at lines 198 and 200 ("below the noise floor," "microseconds to single-digit milliseconds," "tens-of-milliseconds range") have no benchmark behind them anywhere in the repo. I measured the #22 Claude Code adapter at a median of 93.9 ms for process spawn alone, before any Guardian round trip. Different thing being measured, probably, but a reader won't know that. I'd cut the numbers until there's something to cite.

The governance section is doing more work than a FAQ should

Lines 73 to 84 describe a vendor-neutral effort with six workstreams, name individuals as leads, and say "Governance is by workstream leads (the Architecture Review Board) with an Advisory Board."

I went looking for the document that backs this and there isn't one. No GOVERNANCE.md, no MAINTAINERS.md, no CODEOWNERS at root or in .github/. CONTRIBUTING.md:61 says only "Project maintainers handle formal releases" without naming them. Two of the people named in the workstream table aren't in CONTRIBUTORS.md. And the only contact address in the repo is at a single vendor's domain (CODE_OF_CONDUCT.md:58), which sits a bit awkwardly next to the vendor-neutrality claim on line 73.

None of that means the structure isn't real. It means the FAQ becomes the citable record of it, because it's the only one. Six months from now, when someone asks who approved a normative change, the answer is a table in a topics page.

I'd rather see a real GOVERNANCE.md and MAINTAINERS.md land from the maintainers first, with the FAQ linking to them instead of restating them. And for anyone named as a workstream lead, a quick confirmation they're happy to be listed seems worth doing before it's on a public docs site.

One that isn't about the content

The mkdocs.yml change adds the FAQ to the nav, and per CLAUDE.md's hosting note, the site at agentcontrolstandard.ai builds from a separate repo and "changes here do not propagate automatically." So this nav entry doesn't put the FAQ in front of a single reader until somebody mirrors it into the site repo. Worth an issue or a checklist item on the PR, or this ships and nobody sees it.

What I'd do

Land #21 first, rebase items 4, 9, 10 and the diagram at 19 to 28 against its final text. Add the non-normative header and lowercase the RFC 2119 keywords. Fix the checkpoint count and the two overshooting claims. Then either pull the governance section out until there's a GOVERNANCE.md to link, or land that doc alongside this.

The rest of the page is the clearest explanation of ACS that exists right now, which is why I'd like the parts that will get quoted to be the parts that hold up.

One procedural note: CONTRIBUTING.md:42 asks for git commit -s and none of the three commits here have a sign-off. Same on #21 and #22, so it's probably worth a DCO check in CI rather than three separate rebases and a reminder.