@topy-ai/maggie 0.7.49 → 0.7.51

package/bundled-skills/maggie-qa-workflow/SKILL.md

@@ -94,6 +94,36 @@ only after the user explicitly consents and a restore path exists. Overriding
 requests; use network-layer interception as described in the
 [browser inspection contract](../../references/browser-inspection.md).
 
+## Preflight an app dev server
+
+Before browser QA of an Expo / React Native Web app (or any signed-in SPA),
+run:
+
+```bash
+maggie qa app-preflight --project . --app-dir apps/app
+```
+
+It fails when a Metro/Expo dev server was started with `CI=1` or
+`--no-watch` (Metro never rebuilds, so the browser shows the old bundle and
+the change looks broken) or from a folder other than the app (a monorepo root
+or a sibling app serves a different project). In a monorepo with several app
+folders it asks for `--app-dir`.
+
+It warns, with environment variable names and host classes only, when:
+
+- the app stores refresh tokens. If they rotate, two instances refreshing at
+  once revoke the session: render one instance at a time, never parallel
+  iframes or tabs of the signed-in app, and park the QA parent tab on a static
+  same-origin asset such as `/favicon.ico`. `maggie design app-collect`
+  renders viewports sequentially in one tab for this reason;
+- the local app talks to a production-like API. Keep the session read-only:
+  answer approval cards No, do not submit forms, use
+  `maggie design app-collect --read-only --allow-write <refresh path>`, and
+  record the production API in `maggie qa start` so mutating scenarios are
+  refused.
+
+Use `--rotating-refresh-tokens yes|no` when the code scan cannot tell.
+
 ## Check CORS for every method the client uses
 
 Before a release that adds or changes API calls from a browser or webview,

package/bundled-tools/clis/maggie_app_collect.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""Collect signed-in runtime evidence for an app surface (``maggie design app-collect``).
+
+``maggie design app-validate`` checks ``maggie-mobile-app-evidence.v1``; this
+command produces it instead of hand-written browser JavaScript. For each plan
+viewport it renders the route in ONE browser tab, one viewport at a time, at
+the real viewport size (device metrics override, not a scaled iframe), then:
+
+- counts scroll owners: visible ``overflow-y: auto|scroll`` containers at least
+  200 px tall. React Native Web nests ScrollView wrappers, so a container that
+  holds another owner and does not overflow itself is skipped, and so is a
+  same-size wrapper (within 16 px, e.g. a scrollbar gutter) around an owner;
+- proves the fixed shell: the elements at the top and bottom edge keep their
+  position after every scroll owner is scrolled by 300 px;
+- records the tab bar position and pinned (fixed/sticky) regions, geometry only;
+- writes ``<viewport>.png`` at the real viewport size.
+
+Sessions: ``--cdp-url`` attaches to a running Chrome the operator is already
+signed in to (the host session); ``--profile-dir`` launches headless Chrome
+with a dedicated QA profile so a rotated refresh token persists between
+renders. Rendering is sequential in a single tab because apps that rotate
+refresh tokens revoke the grant when two instances refresh at once.
+``--read-only`` fails non-GET requests except ``--allow-write`` URL substrings
+(for example the token refresh endpoint) when the app talks to production.
+Credentials, cookies, storage and page text are never recorded.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
+from cdp_client import Browser, CdpError, attach, launch  # noqa: E402
+
+SCHEMA = "maggie-mobile-app-evidence.v1"
+COLLECTOR = "maggie-design-app-collect"
+WRITE_METHODS = {"POST", "PUT", "PATCH", "DELETE"}
+
+PROBE = r"""
+(async () => {
+  const config = __CONFIG__;
+  const minHeight = config.minScrollHeight;
+  const visible = (el) => { const r = el.getBoundingClientRect(); const s = getComputedStyle(el); return r.width > 0 && r.height > 0 && s.visibility !== 'hidden' && s.display !== 'none'; };
+  const scrollable = (el) => { const s = getComputedStyle(el); return /(auto|scroll)/.test(s.overflowY) && el.clientHeight >= minHeight && visible(el); };
+  const candidates = Array.from(document.querySelectorAll('body *')).filter(scrollable);
+  const overflows = (el) => el.scrollHeight > el.clientHeight + 1;
+  const owners = candidates.filter((el) => {
+    const inner = candidates.filter((other) => other !== el && el.contains(other));
+    if (!inner.length) return true;
+    if (overflows(el)) {
+      // A same-size wrapper (scrollbar gutter) around an owner is still a wrapper.
+      const r = el.getBoundingClientRect();
+      return !inner.some((other) => { const o = other.getBoundingClientRect(); return Math.abs(o.height - r.height) <= 16 && Math.abs(o.width - r.width) <= 16; });
+    }
+    return false;
+  });
+  const doc = document.scrollingElement || document.documentElement;
+  const documentScrolls = doc.scrollHeight > window.innerHeight + 1 && !/hidden|clip/.test(getComputedStyle(document.body).overflowY + getComputedStyle(document.documentElement).overflowY);
+  const pick = (selector, y) => {
+    if (selector) return document.querySelector(selector);
+    let el = document.elementFromPoint(Math.floor(window.innerWidth / 2), y);
+    if (!el || owners.some((o) => o.contains(el))) return null;  // content, not shell
+    // Climb to the outermost ancestor that still contains no scroll owner: the bar itself.
+    while (el.parentElement && el.parentElement !== document.body && !owners.some((o) => el.parentElement.contains(o))) el = el.parentElement;
+    return el;
+  };
+  const header = pick(config.headerSelector, 2);
+  const footer = pick(config.footerSelector, window.innerHeight - 3);
+  const rect = (el) => { if (!el) return null; const r = el.getBoundingClientRect(); return { top: Math.round(r.top), bottom: Math.round(r.bottom), left: Math.round(r.left), width: Math.round(r.width), height: Math.round(r.height) }; };
+  const before = { header: rect(header), footer: rect(footer) };
+  const scrolled = [];
+  for (const owner of owners) { const start = owner.scrollTop; owner.scrollTop = start + 300; scrolled.push([owner, start]); }
+  const winStart = window.scrollY; window.scrollTo(0, winStart + 300);
+  await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+  const after = { header: rect(header), footer: rect(footer) };
+  for (const [owner, start] of scrolled) owner.scrollTop = start;
+  window.scrollTo(0, winStart);
+  const same = (a, b) => !!a && !!b && Math.abs(a.top - b.top) <= 1 && a.height > 0;
+  const fixedHeader = !!header && before.header.top <= 1 && same(before.header, after.header);
+  const fixedFooter = !!footer && before.footer.bottom >= window.innerHeight - 1 && same(before.footer, after.footer);
+  const tablist = document.querySelector(config.tabBarSelector || '[role="tablist"], nav[aria-label*="tab" i]');
+  let tabBar = 'none';
+  if (tablist && visible(tablist)) {
+    const r = tablist.getBoundingClientRect();
+    tabBar = r.bottom >= window.innerHeight - 2 ? 'bottom' : r.top <= 2 && r.width >= window.innerWidth * 0.6 ? 'top' : r.height >= window.innerHeight * 0.6 ? 'side' : 'inline';
+  }
+  const pinned = Array.from(document.querySelectorAll('body *')).filter((el) => { const p = getComputedStyle(el).position; return (p === 'fixed' || p === 'sticky') && visible(el); }).slice(0, 20).map((el) => ({ tag: el.tagName.toLowerCase(), role: el.getAttribute('role') || null, position: getComputedStyle(el).position, rect: rect(el) }));
+  const path = location.pathname.replace(/\/+$/, '') || '/';
+  const want = config.route.replace(/\/+$/, '') || '/';
+  const onRoute = path === want;
+  const signedInMarker = config.signedInSelector ? !!document.querySelector(config.signedInSelector) : null;
+  const signedOutMarker = config.signedOutSelector ? !!document.querySelector(config.signedOutSelector) : false;
+  return {
+    width: window.innerWidth, height: window.innerHeight, deviceScaleFactor: window.devicePixelRatio,
+    scrollOwners: owners.length + (documentScrolls ? 1 : 0), documentScrolls,
+    scrollOwnerGeometry: owners.map(rect), skippedWrappers: candidates.length - owners.length,
+    fixedHeader, fixedFooter, header: before.header, footer: before.footer, tabBar, pinned,
+    onRoute, signedIn: onRoute && signedInMarker !== false && !signedOutMarker,
+  };
+})()
+"""
+
+
+def probe_expression(route: str, options: dict) -> str:
+    config = {"route": route, "minScrollHeight": 200, **options}
+    return PROBE.replace("__CONFIG__", json.dumps(config))
+
+
+def build_evidence(plan: dict, renders: dict[str, dict], session_mode: str, previous: dict | None, warnings: list[str]) -> dict:
+    """Assemble ``maggie-mobile-app-evidence.v1`` from per-viewport probe results."""
+    previous = previous or {}
+    viewports = {}
+    for name, result in renders.items():
+        viewports[name] = {key: result.get(key) for key in ("width", "height", "deviceScaleFactor", "scrollOwners", "documentScrolls", "skippedWrappers", "fixedHeader", "fixedFooter", "tabBar", "header", "footer", "pinned", "scrollOwnerGeometry")}
+        viewports[name].update({"screenshot": f"{name}.png", "captured": bool(result.get("captured")), "fullPage": False})
+    rendered = [result for result in renders.values() if result]
+    signed_in = bool(rendered) and all(result.get("signedIn") for result in rendered)
+    capabilities = previous.get("capabilities") if isinstance(previous.get("capabilities"), dict) else {name: {"states": []} for name in plan.get("capabilities", {})}
+    return {
+        "schemaVersion": SCHEMA,
+        "collector": COLLECTOR,
+        "route": plan.get("route"),
+        "auth": {"signedIn": signed_in, "sessionMode": session_mode, "credentialsRecorded": False},
+        "shell": {"fixedHeader": bool(rendered) and all(r.get("fixedHeader") for r in rendered), "fixedFooter": bool(rendered) and all(r.get("fixedFooter") for r in rendered), "method": "edge elements keep their position after each scroll owner scrolls 300 px; RN-web wrappers that do not overflow are skipped"},
+        "capabilities": capabilities,
+        "viewports": viewports,
+        "warnings": warnings,
+        "status": "collected",
+        "collectedAt": datetime.now(timezone.utc).isoformat(),
+        "mutation": "read-only" if any("read-only" in w for w in warnings) else "not blocked",
+    }
+
+
+def _install_read_only(browser: Browser, allow: list[str], blocked: list[str]) -> None:
+    def paused(params: dict) -> None:
+        request = params.get("request", {})
+        url = request.get("url", "")
+        if request.get("method", "GET").upper() in WRITE_METHODS and not any(token in url for token in allow):
+            blocked.append(f"{request.get('method')} {url.split('?')[0][:120]}")
+            browser.call("Fetch.failRequest", {"requestId": params["requestId"], "errorReason": "BlockedByClient"})
+        else:
+            browser.call("Fetch.continueRequest", {"requestId": params["requestId"]})
+    browser.handlers["Fetch.requestPaused"] = paused
+    browser.call("Fetch.enable", {"patterns": [{"urlPattern": "*", "requestStage": "Request"}]})
+
+
+def collect(plan_path: Path, base_url: str, browser: Browser, session_mode: str, output_dir: Path, options: dict, read_only: bool, allow_write: list[str], settle_ms: int, budget_ms: int) -> dict:
+    plan = json.loads(plan_path.read_text(encoding="utf-8"))
+    if plan.get("mode") != "app-view-init":
+        raise ValueError("plan is not a maggie design app-init plan")
+    route = plan.get("route")
+    viewports = {name: tuple(size) for name, size in plan.get("viewports", {}).items()}
+    if not viewports:
+        raise ValueError("plan has no viewports")
+    warnings: list[str] = []
+    blocked: list[str] = []
+    screenshots = output_dir / "screenshots"
+    screenshots.mkdir(parents=True, exist_ok=True)
+    renders: dict[str, dict] = {}
+    browser.open_tab()
+    browser.call("Page.enable")
+    if read_only:
+        _install_read_only(browser, allow_write, blocked)
+        warnings.append("read-only: non-GET requests were failed except --allow-write matches")
+    url = base_url.rstrip("/") + route
+    for name, (width, height) in viewports.items():  # sequential: one app instance at a time
+        browser.call("Emulation.setDeviceMetricsOverride", {"width": width, "height": height, "deviceScaleFactor": 1, "mobile": width < 768})
+        browser.call("Page.navigate", {"url": url})
+        if browser.wait_for("Page.loadEventFired", budget_ms / 1000) is None:
+            warnings.append(f"{name}: load event not seen within {budget_ms} ms")
+        browser.pump(settle_ms / 1000)
+        result = browser.evaluate(probe_expression(route, options)) or {}
+        shot = browser.call("Page.captureScreenshot", {"format": "png", "captureBeyondViewport": False})
+        (screenshots / f"{name}.png").write_bytes(base64.b64decode(shot["data"]))
+        result["captured"] = True
+        renders[name] = result
+        if not result.get("onRoute"):
+            warnings.append(f"{name}: the app left {route} (likely a sign-in redirect)")
+        time.sleep(0.05)
+    if blocked:
+        warnings.append(f"read-only blocked {len(blocked)} write request(s): " + ", ".join(sorted(set(blocked))[:5]))
+    previous_path = output_dir / "runtime-evidence.json"
+    previous = json.loads(previous_path.read_text(encoding="utf-8")) if previous_path.is_file() else None
+    return build_evidence(plan, renders, session_mode, previous, warnings)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie design app-collect", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--plan", type=Path, required=True, help="plan.json from maggie design app-init")
+    parser.add_argument("--base-url", required=True, help="app origin, e.g. http://localhost:8081")
+    session = parser.add_mutually_exclusive_group(required=True)
+    session.add_argument("--cdp-url", help="attach to a signed-in Chrome started with --remote-debugging-port, e.g. http://127.0.0.1:9222")
+    session.add_argument("--profile-dir", type=Path, help="dedicated QA Chrome profile (never your everyday profile)")
+    parser.add_argument("--headed", action="store_true", help="with --profile-dir, show the window (sign in once, then rerun headless)")
+    parser.add_argument("--chrome", default="", help="Chrome executable (default: google-chrome/chromium on PATH)")
+    parser.add_argument("--header-selector"); parser.add_argument("--footer-selector"); parser.add_argument("--tab-bar-selector")
+    parser.add_argument("--signed-in-selector", help="element present only when signed in"); parser.add_argument("--signed-out-selector", help="element present only when signed out")
+    parser.add_argument("--read-only", action="store_true", help="fail non-GET requests (use when the app talks to production)")
+    parser.add_argument("--allow-write", action="append", default=[], help="URL substring allowed to POST under --read-only (e.g. /auth/refresh)")
+    parser.add_argument("--settle-ms", type=int, default=1500)
+    parser.add_argument("--budget-ms", type=int, default=20000)
+    parser.add_argument("--confirm", action="store_true", help="write runtime-evidence.json and screenshots next to the plan")
+    args = parser.parse_args(argv)
+    plan_path = args.plan.resolve()
+    output_dir = plan_path.parent if args.confirm else Path(__import__("tempfile").mkdtemp(prefix="maggie-app-collect-"))
+    options = {"headerSelector": args.header_selector, "footerSelector": args.footer_selector, "tabBarSelector": args.tab_bar_selector, "signedInSelector": args.signed_in_selector, "signedOutSelector": args.signed_out_selector}
+    browser = None
+    try:
+        if args.cdp_url:
+            browser, mode = attach(args.cdp_url), "attached-host-session"
+        else:
+            from maggie_icon_glyph_check import find_chrome
+            browser, mode = launch(args.chrome or find_chrome(), args.profile_dir.resolve(), headless=not args.headed), "dedicated-profile"
+        evidence = collect(plan_path, args.base_url, browser, mode, output_dir, options, args.read_only, args.allow_write, args.settle_ms, args.budget_ms)
+    except (OSError, ValueError, CdpError, json.JSONDecodeError, RuntimeError) as error:
+        print(f"BLOCKED: maggie-design app-collect: {error}", file=sys.stderr)
+        return 2
+    finally:
+        if browser:
+            browser.close()
+    target = output_dir / "runtime-evidence.json"
+    target.write_text(json.dumps(evidence, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    summary = {"schemaVersion": SCHEMA, "collector": COLLECTOR, "signedIn": evidence["auth"]["signedIn"], "viewports": {name: {k: v.get(k) for k in ("width", "height", "scrollOwners", "fixedHeader", "fixedFooter", "tabBar")} for name, v in evidence["viewports"].items()}, "warnings": evidence["warnings"], "output": str(target), "written": args.confirm}
+    print(json.dumps(summary, indent=2, ensure_ascii=False))
+    print("next: maggie design app-validate --plan " + str(plan_path) + (" --runtime-evidence " + str(target) if not args.confirm else ""), file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_assistant_tools.py

@@ -0,0 +1,302 @@
+#!/usr/bin/env python3
+"""Assistant tool registry checks (``maggie assistant``).
+
+Build an assistant's tools once and expose them to an in-app agent, an MCP
+server and ChatGPT/Claude apps. The product exports its registry as JSON
+(``maggie-assistant-tool-registry.v1``); these commands never import product
+code or call a model.
+
+- ``registry-validate``: names, risk levels, gates, scopes, channels, and the
+  user-facing copy (label, detail, confirm sentence) kept separate from the
+  model-facing description. User copy may not contain snake_case tool names,
+  "the user", or "(from some_tool)" references.
+- ``annotations``: MCP tool annotations derived from risk (and checked against
+  an exported ``tools/list`` with ``--mcp-tools``).
+- ``capability-page``: the "what the assistant can and can't do" page from user
+  copy only, grouped by what needs approval.
+- ``audit-check``: every write in a recorded session has one audit entry, with
+  a readable summary (never a bare UUID) and the right scope (account-level
+  writes are not filed under the open site).
+- ``approval-selftest``: exercises the reference signed one-time approval
+  token (``tools/runtime/assistant_approval.py``).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
+
+SCHEMA = "maggie-assistant-tool-registry.v1"
+RISKS = ("read", "write-reversible", "write-spends", "write-public", "never")
+RISK_ALIASES = {"R0": "read", "W1": "write-reversible", "W2": "write-spends", "W3": "write-public", "W4": "never"}
+CHANNELS = ("in-app", "mcp", "chatgpt", "claude", "cli")
+SCOPES = ("account", "workspace")
+NAME_RE = re.compile(r"^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$|^[a-z][a-z0-9]+$")
+SNAKE_RE = re.compile(r"\b[a-z][a-z0-9]*_[a-z0-9_]+\b")
+THE_USER_RE = re.compile(r"\bthe user('s)?\b", re.I)
+FROM_TOOL_RE = re.compile(r"\((?:from|via|using) [a-z0-9_]+\)", re.I)
+UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.I)
+DESTRUCTIVE_NAME_RE = re.compile(r"_(?:remove|delete|discard|revoke|cancel|unpublish)$")
+
+
+def risk_of(tool: dict) -> str:
+    value = str(tool.get("risk", ""))
+    return RISK_ALIASES.get(value, value)
+
+
+def user_copy_problems(text: str, tool_names: set[str]) -> list[str]:
+    problems = []
+    if SNAKE_RE.search(text) or any(name in text for name in tool_names if "_" in name):
+        problems.append("contains a snake_case tool name")
+    if THE_USER_RE.search(text):
+        problems.append("says 'the user' (address the reader as 'you')")
+    if FROM_TOOL_RE.search(text):
+        problems.append("references another tool in parentheses")
+    return problems
+
+
+def validate_registry(registry: dict) -> dict:
+    errors: list[str] = []
+    warnings: list[str] = []
+    if registry.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    tools = registry.get("tools")
+    if not isinstance(tools, list) or not tools:
+        return {"schemaVersion": "maggie-assistant-registry-validation.v1", "passed": False, "errors": errors + ["tools must be a non-empty array"], "warnings": warnings, "counts": {}}
+    gates = registry.get("gates", {}) if isinstance(registry.get("gates"), dict) else {}
+    names = [str(tool.get("name", "")) for tool in tools if isinstance(tool, dict)]
+    name_set = set(names)
+    for duplicate in sorted({name for name in names if names.count(name) > 1}):
+        errors.append(f"duplicate tool name {duplicate}")
+    counts = {risk: 0 for risk in RISKS}
+    for tool in tools:
+        if not isinstance(tool, dict):
+            errors.append("each tool must be an object"); continue
+        name = str(tool.get("name", ""))
+        where = name or "<unnamed>"
+        if not NAME_RE.match(name) or len(name) > 64:
+            errors.append(f"{where}: name must be lower snake_case, at most 64 characters")
+        risk = risk_of(tool)
+        if risk not in RISKS:
+            errors.append(f"{where}: risk must be one of {', '.join(RISKS)} (or R0/W1/W2/W3/W4)"); continue
+        counts[risk] += 1
+        description = str(tool.get("description", "")).strip()
+        if not description:
+            errors.append(f"{where}: model-facing description is required")
+        elif len(description) > 1024:
+            warnings.append(f"{where}: description is over 1024 characters; models and app reviewers truncate long descriptions")
+        if tool.get("scope") not in SCOPES:
+            errors.append(f"{where}: scope must be account or workspace")
+        channels = tool.get("channels", [])
+        if not isinstance(channels, list) or not channels or any(channel not in CHANNELS for channel in channels):
+            errors.append(f"{where}: channels must list some of {', '.join(CHANNELS)}")
+            channels = []
+        for gate in tool.get("gates", []) or []:
+            if gate not in gates:
+                errors.append(f"{where}: gate {gate!r} is not declared in registry.gates")
+        user = tool.get("user") if isinstance(tool.get("user"), dict) else {}
+        label = str(user.get("label", "")).strip()
+        detail = str(user.get("detail", "")).strip()
+        confirm = str(user.get("confirm", "")).strip()
+        if not label:
+            errors.append(f"{where}: user.label is required (do not derive it from the model description)")
+        elif len(label) > 60:
+            errors.append(f"{where}: user.label is over 60 characters")
+        if detail and len(detail) > 200:
+            warnings.append(f"{where}: user.detail is over 200 characters")
+        if risk not in {"read", "never"} and not confirm:
+            errors.append(f"{where}: writes need user.confirm, the sentence shown on the approval card")
+        for field, text in (("label", label), ("detail", detail), ("confirm", confirm)):
+            for problem in user_copy_problems(text, name_set):
+                errors.append(f"{where}: user.{field} {problem}")
+        if risk == "never" and any(channel != "in-app" for channel in channels):
+            errors.append(f"{where}: a 'never' tool must not be exposed on {', '.join(c for c in channels if c != 'in-app')}; list it under cantDo instead")
+        if risk in {"write-public", "never"} and tool.get("idempotent") is True:
+            warnings.append(f"{where}: public/irreversible writes are rarely idempotent; check idempotent: true")
+        if DESTRUCTIVE_NAME_RE.search(name) and risk in {"read", "write-reversible"}:
+            warnings.append(f"{where}: the name reads as destructive; app reviewers expect destructiveHint, so consider write-public")
+        if tool.get("audit", {}).get("scope") not in (None, tool.get("scope")):
+            errors.append(f"{where}: audit.scope must equal the tool scope (an account-level write is not audited under the open site)")
+    for item in registry.get("cantDo", []) or []:
+        if not isinstance(item, dict) or not str(item.get("text", "")).strip():
+            errors.append("cantDo entries need text (and ideally 'instead')")
+            continue
+        for problem in user_copy_problems(str(item.get("text", "")) + " " + str(item.get("instead", "")), name_set):
+            errors.append(f"cantDo '{str(item['text'])[:40]}': {problem}")
+    return {"schemaVersion": "maggie-assistant-registry-validation.v1", "passed": not errors, "errors": errors, "warnings": warnings, "counts": {"tools": len(tools), **counts}}
+
+
+def annotations_for(tool: dict) -> dict:
+    risk = risk_of(tool)
+    title = str(tool.get("user", {}).get("label", "")).strip() or None
+    value = {
+        "readOnlyHint": risk == "read",
+        "destructiveHint": risk in {"write-public", "never"} or bool(DESTRUCTIVE_NAME_RE.search(str(tool.get("name", "")))),
+        "idempotentHint": risk == "read" or tool.get("idempotent") is True,
+        "openWorldHint": risk == "write-public" or tool.get("openWorld") is True,
+    }
+    if title:
+        value["title"] = title
+    return value
+
+
+def derive_annotations(registry: dict, mcp_tools: dict | None) -> dict:
+    tools = [tool for tool in registry.get("tools", []) if isinstance(tool, dict) and "mcp" in (tool.get("channels") or []) and risk_of(tool) != "never"]
+    derived = {tool["name"]: annotations_for(tool) for tool in tools}
+    report = {"schemaVersion": "maggie-assistant-mcp-annotations.v1", "tools": derived, "drift": []}
+    if mcp_tools is not None:
+        listed = {item.get("name"): item for item in (mcp_tools.get("tools") or mcp_tools.get("result", {}).get("tools") or []) if isinstance(item, dict)}
+        for name, expected in derived.items():
+            actual = listed.get(name)
+            if actual is None:
+                report["drift"].append(f"{name}: in the registry for mcp but not served by the MCP server")
+                continue
+            for key, want in expected.items():
+                got = (actual.get("annotations") or {}).get(key)
+                if key != "title" and got != want:
+                    report["drift"].append(f"{name}: {key} is {got!r}, risk implies {want!r}")
+        for name in sorted(set(listed) - set(derived)):
+            report["drift"].append(f"{name}: served by the MCP server but not in the registry (or marked never)")
+    report["passed"] = not report["drift"]
+    return report
+
+
+def capability_page(registry: dict, title: str) -> tuple[str, dict]:
+    groups = {"read": [], "asks": [], "careful": []}
+    for tool in registry.get("tools", []):
+        risk = risk_of(tool)
+        user = tool.get("user", {})
+        if risk == "never" or tool.get("hidden"):
+            continue
+        entry = {"label": user.get("label", ""), "detail": user.get("detail", ""), "gates": [registry.get("gates", {}).get(g, {}).get("label", g) for g in tool.get("gates", []) or []]}
+        groups["read" if risk == "read" else "careful" if risk == "write-public" else "asks"].append(entry)
+    cant = [{"text": item.get("text", ""), "instead": item.get("instead", "")} for item in registry.get("cantDo", []) or []]
+    for tool in registry.get("tools", []):
+        if risk_of(tool) == "never":
+            cant.append({"text": tool.get("user", {}).get("label", ""), "instead": tool.get("user", {}).get("detail", "")})
+    lines = [f"# {title}", ""]
+    sections = (("read", "Looks things up for you", "No approval needed; nothing changes."), ("asks", "Changes things after you approve", "You see what will change and approve it first."), ("careful", "Publishes or is hard to undo", "Always asks, and says so clearly."))
+    for key, heading, note in sections:
+        if not groups[key]:
+            continue
+        lines += [f"## {heading}", "", note, ""]
+        for entry in sorted(groups[key], key=lambda item: item["label"].lower()):
+            gates = f" _({', '.join(entry['gates'])})_" if entry["gates"] else ""
+            lines.append(f"- **{entry['label']}**" + (f" — {entry['detail']}" if entry["detail"] else "") + gates)
+        lines.append("")
+    if cant:
+        lines += ["## Can't do", ""]
+        for item in cant:
+            lines.append(f"- {item['text']}" + (f" Instead: {item['instead']}" if item["instead"] else ""))
+        lines.append("")
+    data = {"schemaVersion": "maggie-assistant-capability-page.v1", "title": title, "groups": groups, "cantDo": cant}
+    return "\n".join(lines), data
+
+
+def audit_check(registry: dict, session: dict) -> dict:
+    tools = {tool.get("name"): tool for tool in registry.get("tools", []) if isinstance(tool, dict)}
+    errors: list[str] = []
+    calls = [call for call in session.get("calls", []) if isinstance(call, dict)]
+    entries = [entry for entry in session.get("audit", []) if isinstance(entry, dict)]
+    by_action: dict[str, list[dict]] = {}
+    for entry in entries:
+        for action in entry.get("actions", []) or []:
+            by_action.setdefault(str(action.get("actionId", "")), []).append({**action, "scope": entry.get("scope"), "channel": entry.get("channel")})
+    for call in calls:
+        tool = tools.get(call.get("tool"))
+        if tool is None:
+            errors.append(f"{call.get('tool')}: called but not in the registry"); continue
+        if risk_of(tool) == "read":
+            continue
+        action_id = str(call.get("actionId", ""))
+        matches = [a for a in by_action.get(action_id, []) if a.get("tool") == call.get("tool")]
+        if len(matches) != 1:
+            errors.append(f"{call.get('tool')} ({action_id or 'no actionId'}): expected one audit entry, found {len(matches)}"); continue
+        action = matches[0]
+        summary = str(action.get("summary", "")).strip()
+        if not summary or UUID_RE.match(summary) or re.search(r"[0-9a-f]{8}-[0-9a-f]{4}-", summary):
+            errors.append(f"{call.get('tool')}: audit summary must be readable, not a raw ID (fall back to the tool label)")
+        expected_scope = "account" if tool.get("scope") == "account" else call.get("workspace")
+        if expected_scope and action.get("scope") != expected_scope:
+            errors.append(f"{call.get('tool')}: audited under {action.get('scope')!r}, expected {expected_scope!r}")
+        if call.get("ok") is False and not action.get("error"):
+            errors.append(f"{call.get('tool')}: failed call has no audit error")
+    return {"schemaVersion": "maggie-assistant-audit-check.v1", "passed": not errors, "errors": errors, "writes": sum(1 for c in calls if risk_of(tools.get(c.get("tool"), {})) not in {"read", ""})}
+
+
+def approval_selftest() -> dict:
+    import assistant_approval as approval
+    secret = b"selftest-secret-not-for-production"
+    calls = [{"name": "post_schedule", "args": {"postId": "p1", "at": "2026-10-12T09:00:00Z"}}]
+    results = {}
+    token, issued = approval.issue(secret, "key-1", "site-a", calls, now=1000)
+    store = approval.TurnStore(); store.propose("turn-1", token)
+    results["clientSendsOnlyYes"] = approval.verify(secret, store.consume("turn-1"), "key-1", "site-a", calls, now=1001)["id"] == issued["id"]
+    def raises(fn) -> bool:
+        try:
+            fn(); return False
+        except approval.ApprovalError:
+            return True
+    results["singleUse"] = raises(lambda: store.consume("turn-1"))
+    results["expires"] = raises(lambda: approval.verify(secret, token, "key-1", "site-a", calls, now=1000 + 601))
+    results["argsBound"] = raises(lambda: approval.verify(secret, token, "key-1", "site-a", [{"name": "post_schedule", "args": {"postId": "p2"}}], now=1001))
+    results["principalBound"] = raises(lambda: approval.verify(secret, token, "key-2", "site-a", calls, now=1001))
+    results["scopeBound"] = raises(lambda: approval.verify(secret, token, "key-1", "site-b", calls, now=1001))
+    results["tamperRejected"] = raises(lambda: approval.verify(secret, token[:-2] + ("AA" if not token.endswith("AA") else "BB"), "key-1", "site-a", calls, now=1001))
+    results["idempotencyKeyStable"] = approval.idempotency_key(issued["id"], calls[0]) == approval.idempotency_key(issued["id"], dict(calls[0]))
+    return {"schemaVersion": "maggie-assistant-approval-selftest.v1", "passed": all(results.values()), "checks": results}
+
+
+def _read(path: Path) -> dict:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise ValueError(f"{path.name} must be a JSON object")
+    return value
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie assistant", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="command", required=True)
+    validate = sub.add_parser("registry-validate"); validate.add_argument("--registry", type=Path, required=True)
+    annotate = sub.add_parser("annotations"); annotate.add_argument("--registry", type=Path, required=True); annotate.add_argument("--mcp-tools", type=Path, help="exported MCP tools/list JSON to compare")
+    page = sub.add_parser("capability-page"); page.add_argument("--registry", type=Path, required=True); page.add_argument("--title", default="What the assistant can and can't do"); page.add_argument("--output", type=Path, help="Markdown file; JSON is written next to it")
+    audit = sub.add_parser("audit-check"); audit.add_argument("--registry", type=Path, required=True); audit.add_argument("--session", type=Path, required=True, help="recorded calls + audit entries (maggie-assistant-session.v1)")
+    sub.add_parser("approval-selftest")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "approval-selftest":
+            report = approval_selftest()
+        else:
+            registry = _read(args.registry)
+            if args.command == "registry-validate":
+                report = validate_registry(registry)
+            elif args.command == "annotations":
+                report = derive_annotations(registry, _read(args.mcp_tools) if args.mcp_tools else None)
+            elif args.command == "capability-page":
+                checked = validate_registry(registry)
+                if not checked["passed"]:
+                    print(json.dumps(checked, indent=2, ensure_ascii=False)); return 1
+                markdown, data = capability_page(registry, args.title)
+                if args.output:
+                    args.output.parent.mkdir(parents=True, exist_ok=True)
+                    args.output.write_text(markdown + "\n", encoding="utf-8")
+                    args.output.with_suffix(".json").write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+                    report = {"schemaVersion": data["schemaVersion"], "passed": True, "output": str(args.output), "counts": {k: len(v) for k, v in data["groups"].items()}, "cantDo": len(data["cantDo"])}
+                else:
+                    print(markdown); return 0
+            else:
+                report = audit_check(registry, _read(args.session))
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(f"BLOCKED: maggie assistant {args.command}: {error}", file=sys.stderr)
+        return 2
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0 if report.get("passed") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())