@topy-ai/maggie 0.7.53 → 0.7.55

package/bundled-tools/clis/maggie_assistant_tools.py

@@ -6,7 +6,8 @@ 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
+- ``registry-validate``: names, risk levels, gates, scopes, channels, clipped
+  lists, the report inbox, unattended-caller caps and sign-in defaults, 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.
@@ -17,6 +18,10 @@ code or call a model.
 - ``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).
+- ``list-check``: a recorded list result marks every item whose declared
+  field was shortened (``clipped``) and carries the id its get tool needs.
+- ``report-check``: a report an agent is about to save to the report inbox
+  (title, one-line summary, Markdown body) fits the limits and holds no secret.
 - ``approval-selftest``: exercises the reference signed one-time approval
   token and standing workflow approvals (``tools/runtime/assistant_approval.py``).
 """
@@ -187,10 +192,222 @@ def validate_registry(registry: dict) -> dict:
             errors.append("visitorPolicy.factsOnly must be true: answers come from the business's own facts, never general knowledge about prices or health")
         if policy.get("cardDetails") != "never":
             errors.append("visitorPolicy.cardDetails must be never: the chat never asks for or accepts card numbers")
+    by_name = {str(t.get("name")): t for t in tools if isinstance(t, dict)}
+    check_clips(by_name, errors, warnings)
+    check_unattended(registry, by_name, servers, errors, warnings)
+    check_report_inbox(registry, by_name, errors)
     public_tools = [t.get("name") for t in tools if isinstance(t, dict) and any(servers.get(s, {}).get("auth") == "none" for s in t.get("mcpServers", []) or [])]
     return {"schemaVersion": "maggie-assistant-registry-validation.v1", "passed": not errors, "errors": errors, "warnings": warnings, "counts": {"tools": len(tools), **counts, "cards": sum(1 for t in tools if isinstance(t, dict) and t.get("card")), "publicMcpTools": len(public_tools)}}
 
 
+CLIP_WORDS_RE = re.compile(r"\b(?:clipped|shortened|truncated|cut to|first \d+ characters|~?\d+-character)\b", re.I)
+WRITE_RISKS = ("write-reversible", "write-spends", "write-public")
+
+
+def check_clips(by_name: dict[str, dict], errors: list[str], warnings: list[str]) -> None:
+    """A list tool that shortens long fields says so per item and names a get tool with the full text.
+
+    An agent checking what will be published must read the full text; a list that
+    silently clips makes it report "cut off mid-sentence" for text that is whole.
+    """
+    for name, tool in by_name.items():
+        clips = tool.get("clips")
+        if clips is None:
+            if risk_of(tool) == "read" and CLIP_WORDS_RE.search(str(tool.get("description", ""))):
+                warnings.append(f"{name}: the description says results are shortened; declare clips (fields, maxChars, getTool) so each item is marked and the full text has a get tool")
+            continue
+        if not isinstance(clips, dict):
+            errors.append(f"{name}: clips must be an object with fields, maxChars and getTool"); continue
+        if risk_of(tool) != "read":
+            errors.append(f"{name}: clips belongs to a read (list) tool")
+        fields = clips.get("fields")
+        if not isinstance(fields, list) or not fields or not all(isinstance(f, str) and f for f in fields):
+            errors.append(f"{name}: clips.fields must name the shortened fields")
+        if not isinstance(clips.get("maxChars"), int) or clips["maxChars"] < 1:
+            errors.append(f"{name}: clips.maxChars must be a positive integer")
+        get_name = str(clips.get("getTool", ""))
+        get_tool = by_name.get(get_name)
+        if get_tool is None:
+            errors.append(f"{name}: clips.getTool {get_name or '<missing>'!r} is not in the registry; a clipped list needs a get tool that returns the full text"); continue
+        if risk_of(get_tool) != "read":
+            errors.append(f"{name}: clips.getTool {get_name} must be a read tool")
+        if get_tool.get("scope") != tool.get("scope"):
+            errors.append(f"{name}: clips.getTool {get_name} must have the same scope as the list")
+        missing = [c for c in tool.get("channels") or [] if c not in (get_tool.get("channels") or [])]
+        if missing:
+            errors.append(f"{name}: clips.getTool {get_name} is not on {', '.join(missing)}; every caller of the list must be able to read the full text")
+
+
+def oauth_full_set(by_name: dict[str, dict], server: str | None) -> set[str]:
+    """The tools a signed-in caller's role can reach on MCP (the server filters by role at call time)."""
+    names = set()
+    for name, tool in by_name.items():
+        if risk_of(tool) == "never" or "mcp" not in (tool.get("channels") or []):
+            continue
+        if server and tool.get("mcpServers") and server not in tool["mcpServers"]:
+            continue
+        names.add(name)
+    return names
+
+
+def check_unattended(registry: dict, by_name: dict[str, dict], servers: dict, errors: list[str], warnings: list[str]) -> None:
+    """Limits for callers no person watches: agent keys and sign-in (OAuth) grants used by routines.
+
+    A prompt is not a limit. Every write such a caller can reach needs a daily cap
+    that the server counts; the OAuth default tool set is the role's whole set (a
+    narrower default needs a reason); an agent key cannot confirm previews.
+    """
+    policy = registry.get("unattended")
+    oauth_servers = [name for name, server in servers.items() if server.get("auth") == "oauth"]
+    if policy is None:
+        if oauth_servers and any(risk_of(by_name[n]) in WRITE_RISKS for n in oauth_full_set(by_name, oauth_servers[0])):
+            warnings.append("a signed-in MCP server exposes writes but registry.unattended is missing; declare server-enforced daily caps for agent keys and OAuth grants")
+        return
+    if not isinstance(policy, dict):
+        errors.append("unattended must be an object"); return
+    if policy.get("enforcedBy") != "server":
+        errors.append("unattended.enforcedBy must be server: caps kept only in a routine's prompt are not limits")
+    keys = policy.get("agentKeys")
+    if keys is not None:
+        if not isinstance(keys, dict):
+            errors.append("unattended.agentKeys must be an object")
+        else:
+            if keys.get("canConfirmPreviews") is not False:
+                errors.append("unattended.agentKeys.canConfirmPreviews must be false: an agent key runs only the writes its standing permission covers")
+            if keys.get("refusalReturnsReason") is not True:
+                errors.append("unattended.agentKeys.refusalReturnsReason must be true: a refused write says why (e.g. today's limit is used) instead of returning a preview nobody can confirm")
+            standing = keys.get("standingTools") if isinstance(keys.get("standingTools"), dict) else {}
+            for name, cap in standing.items():
+                tool = by_name.get(name)
+                if tool is None:
+                    errors.append(f"unattended.agentKeys.standingTools: {name} is not in the registry"); continue
+                if risk_of(tool) not in ("write-reversible", "write-spends"):
+                    errors.append(f"unattended.agentKeys.standingTools: {name} is {risk_of(tool)}; standing permissions cover reversible or spending writes only, never public or irreversible ones")
+                if not isinstance(cap, dict) or not isinstance(cap.get("perDay"), int) or cap["perDay"] < 1:
+                    errors.append(f"unattended.agentKeys.standingTools: {name} needs perDay, the daily cap the server counts")
+    oauth = policy.get("oauth")
+    if oauth is None:
+        if oauth_servers:
+            errors.append("unattended.oauth is required when a signed-in (oauth) MCP server is declared: a sign-in grant acts as the full person")
+        return
+    if not isinstance(oauth, dict):
+        errors.append("unattended.oauth must be an object"); return
+    server = oauth.get("server") or (oauth_servers[0] if oauth_servers else None)
+    if server and server not in servers:
+        errors.append(f"unattended.oauth.server {server!r} is not declared in registry.mcpServers")
+    full = oauth_full_set(by_name, server)
+    default = oauth.get("defaultTools", "role")
+    if default == "role":
+        reachable = full
+    elif isinstance(default, list):
+        unknown = sorted(set(map(str, default)) - full)
+        if unknown:
+            errors.append(f"unattended.oauth.defaultTools names tools the role can't reach on MCP: {', '.join(unknown)}")
+        reachable = set(map(str, default)) & full
+        left_out = sorted(full - reachable)
+        if left_out and not str(oauth.get("narrowedReason", "")).strip():
+            errors.append(f"unattended.oauth.defaultTools exposes {len(reachable)} of the role's {len(full)} tools (missing e.g. {', '.join(left_out[:5])}); a routine connected by sign-in can't reach the rest. Use \"role\" or give narrowedReason")
+    else:
+        errors.append("unattended.oauth.defaultTools must be \"role\" (the caller's role's full set) or a list of tools"); reachable = full
+    per_tool = oauth.get("perToolPerDay") if isinstance(oauth.get("perToolPerDay"), dict) else {}
+    total = oauth.get("dailyWriteLimit")
+    has_total = isinstance(total, int) and total >= 1
+    for name in sorted(reachable):
+        if risk_of(by_name[name]) not in WRITE_RISKS:
+            continue
+        cap = per_tool.get(name)
+        if not (isinstance(cap, int) and cap >= 1) and not has_total:
+            errors.append(f"unattended.oauth: {name} is a write reachable by a sign-in grant with no server cap; set perToolPerDay.{name} or dailyWriteLimit")
+
+
+REPORT_LIMITS = {"titleMaxChars": 120, "summaryMaxChars": 500, "bodyMaxChars": 50000}
+
+
+def check_report_inbox(registry: dict, by_name: dict[str, dict], errors: list[str]) -> None:
+    """One place where scheduled agents leave their results: save, list, get; capped; bodies untrusted."""
+    inbox = registry.get("reportInbox")
+    if inbox is None:
+        return
+    if not isinstance(inbox, dict):
+        errors.append("reportInbox must be an object"); return
+    names = inbox.get("tools") if isinstance(inbox.get("tools"), dict) else {}
+    expected = {"save": ("write-reversible",), "list": ("read",), "get": ("read",)}
+    for role, risks in expected.items():
+        name = str(names.get(role, ""))
+        tool = by_name.get(name)
+        if tool is None:
+            errors.append(f"reportInbox.tools.{role} {name or '<missing>'!r} is not in the registry"); continue
+        if risk_of(tool) not in risks:
+            errors.append(f"reportInbox.tools.{role} {name} must be {risks[0]} (saving a report changes nothing else)")
+        if tool.get("scope") != "workspace":
+            errors.append(f"reportInbox.tools.{role} {name}: reports belong to one website (scope workspace)")
+    if not isinstance(inbox.get("perSitePerDay"), int) or inbox["perSitePerDay"] < 1:
+        errors.append("reportInbox.perSitePerDay is required: the server caps agent reports per website per day")
+    for key, ceiling in REPORT_LIMITS.items():
+        value = inbox.get(key, ceiling)
+        if not isinstance(value, int) or value < 1:
+            errors.append(f"reportInbox.{key} must be a positive integer")
+    if not isinstance(inbox.get("retentionDays"), int) or inbox["retentionDays"] < 1:
+        errors.append("reportInbox.retentionDays is required")
+    untrusted = set(inbox.get("untrusted") or [])
+    missing = sorted({"title", "summary", "body"} - untrusted)
+    if missing:
+        errors.append(f"reportInbox.untrusted must include {', '.join(missing)}: an agent wrote them, so readers treat them as data, never instructions")
+
+
+def list_check(registry: dict, tool_name: str, result: dict) -> dict:
+    """Check a recorded list result: every item whose declared field was shortened says so."""
+    tool = next((t for t in registry.get("tools", []) if isinstance(t, dict) and t.get("name") == tool_name), None)
+    errors: list[str] = []
+    if tool is None or not isinstance(tool.get("clips"), dict):
+        return {"schemaVersion": "maggie-assistant-list-check.v1", "passed": False, "errors": [f"{tool_name}: not in the registry or declares no clips"], "items": 0, "clipped": 0}
+    clips = tool["clips"]
+    id_field = str(clips.get("idField", "id"))
+    max_chars = int(clips.get("maxChars", 0) or 0)
+    items = result.get("items") if isinstance(result.get("items"), list) else result.get("result", {}).get("items", []) if isinstance(result.get("result"), dict) else []
+    clipped = 0
+    for index, item in enumerate(items):
+        if not isinstance(item, dict):
+            continue
+        where = f"item {index} ({item.get(id_field, 'no ' + id_field)})"
+        if item.get(id_field) in (None, ""):
+            errors.append(f"{where}: has no {id_field}, so the full text can't be fetched with {clips.get('getTool')}")
+        marker = item.get("clipped")
+        for field in clips.get("fields", []):
+            text = item.get(field)
+            if not isinstance(text, str):
+                continue
+            shortened = (max_chars and len(text) >= max_chars) or text.rstrip().endswith(("…", "..."))
+            flagged = marker is True or (isinstance(marker, list) and field in marker)
+            if shortened and not flagged:
+                errors.append(f"{where}: {field} looks shortened ({len(text)} characters) but the item does not say clipped")
+            if flagged:
+                clipped += 1
+    return {"schemaVersion": "maggie-assistant-list-check.v1", "passed": not errors, "errors": errors, "items": len(items), "clipped": clipped, "getTool": clips.get("getTool")}
+
+
+def report_check(report: dict, inbox: dict | None = None) -> dict:
+    """Check a report an agent is about to save (maggie-assistant-report.v1)."""
+    limits = {**REPORT_LIMITS, **{k: v for k, v in (inbox or {}).items() if k in REPORT_LIMITS and isinstance(v, int)}}
+    errors: list[str] = []
+    title = str(report.get("title", "")).strip()
+    summary = str(report.get("summary", "")).strip()
+    body = str(report.get("body_md", report.get("body", "")))
+    if not title:
+        errors.append("title is required")
+    elif len(title) > limits["titleMaxChars"]:
+        errors.append(f"title is over {limits['titleMaxChars']} characters")
+    if not summary:
+        errors.append("summary is required: one or two sentences shown in the inbox")
+    elif len(summary) > limits["summaryMaxChars"]:
+        errors.append(f"summary is over {limits['summaryMaxChars']} characters")
+    if len(body) > limits["bodyMaxChars"]:
+        errors.append(f"body is over {limits['bodyMaxChars']} characters")
+    if re.search(r"(?i)\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{8,}|\bBearer\s+[A-Za-z0-9._-]{20,}|-----BEGIN [A-Z ]*PRIVATE KEY", title + summary + body):
+        errors.append("the report contains something that looks like a secret; remove it before saving")
+    return {"schemaVersion": "maggie-assistant-report-check.v1", "passed": not errors, "errors": errors, "chars": {"title": len(title), "summary": len(summary), "body": len(body)}}
+
+
 def annotations_for(tool: dict) -> dict:
     risk = risk_of(tool)
     title = str(tool.get("user", {}).get("label", "")).strip() or None
@@ -348,14 +565,21 @@ def main(argv: list[str] | None = None) -> int:
     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")
+    lc = sub.add_parser("list-check"); lc.add_argument("--registry", type=Path, required=True); lc.add_argument("--tool", required=True); lc.add_argument("--result", type=Path, required=True, help="a recorded result of the list tool")
+    rc = sub.add_parser("report-check"); rc.add_argument("--report", type=Path, required=True, help="the report about to be saved (title, summary, body_md)"); rc.add_argument("--registry", type=Path, help="use this registry's reportInbox limits")
     args = parser.parse_args(argv)
     try:
         if args.command == "approval-selftest":
             report = approval_selftest()
+        elif args.command == "report-check":
+            inbox = _read(args.registry).get("reportInbox") if args.registry else None
+            report = report_check(_read(args.report), inbox if isinstance(inbox, dict) else None)
         else:
             registry = _read(args.registry)
             if args.command == "registry-validate":
                 report = validate_registry(registry)
+            elif args.command == "list-check":
+                report = list_check(registry, args.tool, _read(args.result))
             elif args.command == "annotations":
                 report = derive_annotations(registry, _read(args.mcp_tools) if args.mcp_tools else None)
             elif args.command == "capability-page":

package/bundled-tools/clis/maggie_booking.py

@@ -32,11 +32,9 @@ DEFAULT_OPS_EVIDENCE_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "booking-ops-evi
 DEFAULT_BROWSER_EVIDENCE_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "booking-browser-evidence-v2.json"
 DEFAULT_STRIPE_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "stripe-booking-capabilities-v1.json"
 DEFAULT_VOUCHER_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "booking-voucher-lifecycle-v1.json"
-EXECUTION_BOARD = (
-    CONTRACTS_ROOT / "maggiedash" / "execution-board.json"
-    if PACKAGED_CONTRACTS_ROOT.is_dir()
-    else REPO_ROOT / "docs" / "maggiedash-booking" / "EXECUTION-BOARD.json"
-)
+# The Booking delivery board is a maintainer document of the Maggie source
+# repository; the npm package does not ship it (config/release-privacy.json).
+EXECUTION_BOARD = REPO_ROOT / "docs" / "maggiedash-booking" / "EXECUTION-BOARD.json"
 
 
 def load_json(path: Path) -> dict:
@@ -57,6 +55,8 @@ def load_gate_json(path: Path, label: str) -> tuple[dict | None, str | None]:
 
 
 def load_execution_board(path: Path = EXECUTION_BOARD) -> dict:
+    if not path.is_file():
+        raise RuntimeError("the Booking delivery board lives in the Maggie source repository (docs/maggiedash-booking/EXECUTION-BOARD.json); pass --board PATH")
     board = load_json(path)
     if board.get("schemaVersion") != "maggiedash-booking-execution-board.v1":
         raise RuntimeError("unsupported Booking execution board schema")
@@ -661,9 +661,9 @@ def booking_setup_result(root: Path, environment: dict[str, str] | None = None)
     stripe_webhook = has("STRIPE_WEBHOOK_SECRET")
     stripe_complete = stripe_secret and stripe_webhook
     stripe_partial = stripe_secret != stripe_webhook
-    stripe_key_help = "STRIPE_SECRET_KEY (or existing ORA alias ST_SECRECT_KEY)"
+    stripe_key_help = "STRIPE_SECRET_KEY (or the legacy alias ST_SECRECT_KEY)"
     stripe_detail = (
-        "Recognizes ORA's existing ST_SECRECT_KEY alias; prefer STRIPE_SECRET_KEY for new deployments. Verify the connection in Booking Overview."
+        "Recognizes the legacy ST_SECRECT_KEY alias; prefer STRIPE_SECRET_KEY for new deployments. Verify the connection in Booking Overview."
         if stripe_legacy_alias and stripe_complete
         else f"Both {stripe_key_help} and STRIPE_WEBHOOK_SECRET are required for online payments."
         if stripe_partial
@@ -872,7 +872,8 @@ def command_install(args: argparse.Namespace) -> int:
         return 2
     root = project_path(args)
     dash = Path(__file__).with_name("maggie_dash.py")
-    command = [sys.executable, str(dash), "install", "--project", str(root), "--host", args.host]
+    # Booking is an optional MaggieDash module: install the core and Booking.
+    command = [sys.executable, str(dash), "install", "--project", str(root), "--host", args.host, "--with", "booking"]
     if args.source:
         command.extend(["--source", args.source])
     if args.ref:

package/bundled-tools/clis/maggie_dash.py

@@ -252,7 +252,7 @@ def merge_astro_middleware(path: Path) -> dict[str, object]:
     return {"status": "updated", "reason": "inserted idempotent Maggie rewrite block"}
 
 
-def manifest_host_file_pairs(source: Path, manifest: dict[str, object], root: Path, framework: str | None) -> list[tuple[Path, Path, Path]]:
+def manifest_host_file_pairs(source: Path, manifest: dict[str, object], root: Path, framework: str | None, required: bool = True) -> list[tuple[Path, Path, Path]]:
     """Return non-destructive host files for a declared framework adapter."""
     if not framework:
         return []
@@ -260,6 +260,8 @@ def manifest_host_file_pairs(source: Path, manifest: dict[str, object], root: Pa
     if not isinstance(bootstrap, dict):
         return []
     spec = bootstrap.get(framework)
+    if not isinstance(spec, dict) and not required:
+        return []
     if not isinstance(spec, dict):
         raise RuntimeError(
             f"MaggieDash distribution at {source} does not provide a {framework} host bootstrap; "
@@ -288,6 +290,128 @@ def manifest_host_file_pairs(source: Path, manifest: dict[str, object], root: Pa
     return pairs
 
 
+CORE_MODULE = "core"
+
+
+def module_names(manifest: dict[str, object]) -> list[str]:
+    modules = manifest.get("modules")
+    return sorted(modules) if isinstance(modules, dict) else []
+
+
+def effective_manifest(manifest: dict[str, object], modules: list[str]) -> dict[str, object]:
+    """Core entries plus the root files and workspaces of the chosen modules."""
+    result = dict(manifest)
+    specs = manifest.get("modules") if isinstance(manifest.get("modules"), dict) else {}
+    root_files = list(manifest.get("rootFiles", []))
+    workspaces = list(manifest.get("workspaces", []))
+    for name in modules:
+        spec = specs.get(name) or {}
+        root_files.extend(spec.get("rootFiles", []))
+        workspaces.extend(spec.get("workspaces", []))
+    result["rootFiles"] = root_files
+    result["workspaces"] = workspaces
+    return result
+
+
+def resolve_modules(manifest: dict[str, object], requested: list[str], previous: list[str]) -> list[str]:
+    available = module_names(manifest)
+    if requested and not available:
+        # A release without the module split installs everything already.
+        return []
+    unknown = sorted(set(requested) - set(available))
+    if unknown:
+        raise RuntimeError(f"unknown MaggieDash module(s): {', '.join(unknown)}; this release offers: {', '.join(available) or 'none'}")
+    # Re-running install keeps refreshing modules that were added before.
+    return sorted((set(requested) | set(previous)) & set(available))
+
+
+def installed_state(root: Path) -> dict[str, object]:
+    try:
+        value = json.loads((root / ".maggie" / "dash-install.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+def package_dependencies(root: Path) -> set[str]:
+    try:
+        value = json.loads((root / "package.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return set()
+    return set(value.get("dependencies") or {}) | set(value.get("devDependencies") or {})
+
+
+SERVICE_WORDS = re.compile(r"\b(book (?:now|an? (?:appointment|session|treatment|table))|appointments?|treatments?|reservations?|book online|opening hours)\b", re.I)
+LOCALE_DIR = re.compile(r"^(?:[a-z]{2}(?:-[a-z]{2,4})?)$")
+
+
+def analyse_host(root: Path, framework: str | None) -> dict[str, object]:
+    """What the host already has, read from files only (nothing is executed)."""
+    deps = package_dependencies(root)
+    auth = sorted(name for name in deps if name in {"firebase", "firebase-admin", "next-auth", "lucia", "better-auth", "@supabase/supabase-js", "@supabase/ssr", "auth-astro"} or name.startswith(("@clerk/", "@auth/")))
+    database = sorted(name for name in deps if name in {"pg", "postgres", "@neondatabase/serverless", "drizzle-orm", "prisma", "@prisma/client", "mysql2", "better-sqlite3", "@libsql/client", "kysely"})
+    for config in ("wrangler.json", "wrangler.jsonc", "wrangler.toml"):
+        path = root / config
+        if path.is_file() and "d1_databases" in path.read_text(encoding="utf-8", errors="replace"):
+            database.append("cloudflare-d1")
+    payments = sorted(name for name in deps if name in {"stripe", "@stripe/stripe-js", "@paypal/checkout-server-sdk", "@lemonsqueezy/lemonsqueezy.js"})
+    source = root / "src"
+    service_hits: list[str] = []
+    if source.is_dir():
+        for path in sorted(source.rglob("*")):
+            if len(service_hits) >= 5:
+                break
+            if path.is_file() and path.suffix in {".astro", ".md", ".mdx", ".tsx", ".jsx", ".ts", ".json", ".html", ".vue", ".svelte"} and "_maggie" not in path.parts and "maggie" not in path.parts:
+                try:
+                    if SERVICE_WORDS.search(path.read_text(encoding="utf-8", errors="replace")[:200_000]):
+                        service_hits.append(str(path.relative_to(root)))
+                except OSError:
+                    continue
+    blog = any((root / candidate).exists() for candidate in ("src/content/blog", "src/content/posts", "src/pages/blog", "src/pages/blog.astro", "src/pages/posts", "content/blog", "app/blog"))
+    locales: set[str] = set()
+    for pages in (root / "src" / "pages", root / "app"):
+        if pages.is_dir():
+            locales.update(child.name for child in pages.iterdir() if child.is_dir() and LOCALE_DIR.match(child.name) and child.name not in {"api", "og"})
+    astro_config = next((path for path in root.glob("astro.config.*")), None)
+    if astro_config:
+        match = re.search(r"locales\s*:\s*\[([^\]]+)\]", astro_config.read_text(encoding="utf-8", errors="replace"))
+        if match:
+            locales.update(re.findall(r"[\"']([A-Za-z-]+)[\"']", match.group(1)))
+    return {
+        "framework": framework,
+        "auth": auth,
+        "database": sorted(set(database)),
+        "payments": payments,
+        "sellsServices": bool(service_hits),
+        "serviceEvidence": service_hits,
+        "blog": blog,
+        "locales": sorted(locales),
+    }
+
+
+def recommendations(analysis: dict[str, object], available: list[str], installed: list[str]) -> list[dict[str, str]]:
+    result: list[dict[str, str]] = []
+    if "booking" in available and "booking" not in installed:
+        if analysis.get("sellsServices"):
+            notes = []
+            if not any(name in {"pg", "postgres", "@neondatabase/serverless"} for name in analysis.get("database", [])):
+                notes.append("it needs PostgreSQL, which this project does not use yet")
+            if analysis.get("auth"):
+                notes.append(f"the site already signs people in with {', '.join(analysis['auth'])}; MaggieDash keeps its own staff sign-in")
+            reason = "The site offers appointments or services (" + ", ".join(analysis.get("serviceEvidence", [])[:3]) + ")" + ("; " + "; ".join(notes) if notes else "")
+            result.append({"kind": "module", "module": "booking", "recommended": "yes", "reason": reason, "command": "maggie dash add booking --confirm"})
+        else:
+            result.append({"kind": "module", "module": "booking", "recommended": "no", "reason": "No appointments or bookable services found in src/; add it only if the business takes bookings.", "command": "maggie dash add booking --confirm"})
+    if analysis.get("blog"):
+        result.append({"kind": "skill", "skill": "maggie-blog", "recommended": "yes", "reason": "The site has a blog; manage posts from the dashboard Blog panel.", "command": "use the maggie-blog skill"})
+        result.append({"kind": "skill", "skill": "maggie-social-share", "recommended": "maybe", "reason": "Blog posts can be shared to social channels after publishing.", "command": "use the maggie-social-share skill"})
+    else:
+        result.append({"kind": "skill", "skill": "maggie-blog-bootstrap", "recommended": "maybe", "reason": "No blog found; add one only if the site will publish articles.", "command": "use the maggie-blog-bootstrap skill"})
+    if len(analysis.get("locales", [])) > 1:
+        result.append({"kind": "skill", "skill": "maggie-content-localization", "recommended": "yes", "reason": f"The site serves {', '.join(analysis['locales'])}; keep translations in the Languages panel.", "command": "use the maggie-content-localization skill"})
+    return result
+
+
 def command_install_diff(source: Path, manifest: dict[str, object], target: Path, compare_dir: Path | None, force: bool, host_pairs: list[tuple[Path, Path, Path]] | None = None, host_framework: str | None = None) -> dict[str, object]:
     pairs = manifest_file_pairs(source, manifest, target)
     root_pairs = manifest_root_file_pairs(source, manifest, target.parents[1])
@@ -386,7 +510,16 @@ def command_install(args: argparse.Namespace) -> int:
             raise RuntimeError("unsupported MaggieDash distribution schema")
         if manifest.get("target") != "_maggie/admin" and args.target == "_maggie/admin":
             raise RuntimeError("MaggieDash manifest target is not ./_maggie/admin")
+        previous = installed_state(root)
+        legacy = not module_names(manifest)
+        modules = resolve_modules(manifest, list(getattr(args, "with_modules", None) or []) + (module_names(manifest) if getattr(args, "all_modules", False) else []), [name for name in previous.get("modules", []) if name != CORE_MODULE])
+        module_specs = manifest.get("modules") if isinstance(manifest.get("modules"), dict) else {}
+        manifest = effective_manifest(manifest, modules)
         host_pairs = manifest_host_file_pairs(source, manifest, root, host_framework)
+        for name in modules:
+            host_pairs += manifest_host_file_pairs(source, module_specs[name], root, host_framework, required=False)
+        analysis = analyse_host(root, host_framework)
+        advice = recommendations(analysis, module_names({"modules": module_specs}), modules)
         compare_dir = None
         if args.existing_dir:
             compare_dir = Path(args.existing_dir).expanduser()
@@ -394,7 +527,9 @@ def command_install(args: argparse.Namespace) -> int:
                 compare_dir = root / compare_dir
             compare_dir = compare_dir.resolve()
         if args.dry_run or args.diff:
-            emit(command_install_diff(source, manifest, target, compare_dir, args.force, host_pairs, host_framework))
+            plan = command_install_diff(source, manifest, target, compare_dir, args.force, host_pairs, host_framework)
+            plan.update({"modules": [CORE_MODULE, *modules] if not legacy else ["all (release without modules)"], "availableModules": module_names({"modules": module_specs}), "host": analysis, "recommendations": advice})
+            emit(plan)
             return 0
         installed: list[str] = []
         preserved: list[str] = []
@@ -471,18 +606,39 @@ def command_install(args: argparse.Namespace) -> int:
             "hostPreserved": sorted(set(host_preserved)),
             "hostUpdated": sorted(set(host_updated)),
             "hostWarnings": sorted(set(host_warnings)),
+            "modules": [CORE_MODULE, *modules] if not legacy else ["legacy-all"],
             "updatedAt": utc_now(),
         }
         state_path = root / ".maggie" / "dash-install.json"
         state_path.parent.mkdir(parents=True, exist_ok=True)
         state_path.write_text(json.dumps(state, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-        emit({"status": "needs-attention" if host_warnings else "installed", "version": manifest.get("version"), "target": str(target), "hostFramework": host_framework, "hostInstalled": len(set(host_installed)), "hostPreserved": len(set(host_preserved)), "hostUpdated": len(set(host_updated)), "hostWarnings": host_warnings, "installed": len(set(installed)), "preserved": len(set(preserved)), "state": str(state_path)})
+        notices = ["this MaggieDash release has no module split, so its Booking workspace was installed with the core; use MaggieDash 0.2.14 or later to install the core first"] if legacy and manifest.get("workspaces") else []
+        emit({"status": "needs-attention" if host_warnings else "installed", "version": manifest.get("version"), "modules": state["modules"], "notices": notices, "recommendations": advice, "next": "Add a recommended module with `maggie dash add <module> --confirm`; nothing optional is installed without that step." if advice and not legacy else None, "target": str(target), "hostFramework": host_framework, "hostInstalled": len(set(host_installed)), "hostPreserved": len(set(host_preserved)), "hostUpdated": len(set(host_updated)), "hostWarnings": host_warnings, "installed": len(set(installed)), "preserved": len(set(preserved)), "state": str(state_path)})
         return 1 if host_warnings else 0
     finally:
         if temporary is not None:
             temporary.cleanup()
 
 
+def command_add(args: argparse.Namespace) -> int:
+    """Install one optional module next to an existing (or new) core install."""
+    args.with_modules = list(args.modules)
+    args.all_modules = False
+    return command_install(args)
+
+
+def command_recommend(args: argparse.Namespace) -> int:
+    root = project_root(args)
+    framework = detect_host_framework(root, args.host)
+    state = installed_state(root)
+    installed = [name for name in state.get("modules", []) if name != CORE_MODULE]
+    analysis = analyse_host(root, framework)
+    # The module list comes from the installed release when known; Booking is
+    # the optional code module MaggieDash ships today.
+    emit({"status": "recommendations", "installed": state.get("modules", []), "host": analysis, "recommendations": recommendations(analysis, ["booking"], installed)})
+    return 0
+
+
 def command_init(args: argparse.Namespace) -> int:
     require_confirm(args)
     root = project_root(args)
@@ -832,8 +988,22 @@ def parser() -> argparse.ArgumentParser:
     install.add_argument("--dry-run", action="store_true", help="show the install plan without writing files")
     install.add_argument("--diff", action="store_true", help="show the install plan and compare with an existing workspace")
     install.add_argument("--existing-dir", help="existing dashboard source directory to compare during --diff")
+    install.add_argument("--with", dest="with_modules", action="append", default=[], metavar="MODULE", help="also install an optional module (repeatable), e.g. --with booking")
+    install.add_argument("--all-modules", action="store_true", help="install every optional module (the pre-0.2.14 behaviour)")
     install.add_argument("--confirm", action="store_true")
     install.set_defaults(func=command_install)
+    add = sub.add_parser("add", help="add an optional MaggieDash module (e.g. booking) to an installed core")
+    add.add_argument("modules", nargs="+", metavar="MODULE")
+    for flag, options in (("--project", {"default": "."}), ("--source", {"help": "local checkout or Git URL; defaults to MaggieDash repository"}), ("--ref", {"default": "main"}), ("--target", {"default": "_maggie/admin"}), ("--existing-dir", {})):
+        add.add_argument(flag, **options)
+    add.add_argument("--host", choices=["auto", "astro", "none"], default="auto")
+    for flag in ("--force", "--dry-run", "--diff", "--confirm"):
+        add.add_argument(flag, action="store_true")
+    add.set_defaults(func=command_add)
+    recommend = sub.add_parser("recommend", help="analyse the host project and recommend optional modules and skills")
+    recommend.add_argument("--project", default=".")
+    recommend.add_argument("--host", choices=["auto", "astro", "none"], default="auto")
+    recommend.set_defaults(func=command_recommend)
     status = sub.add_parser("status", help="inspect project and documents")
     status.add_argument("--project", default=".")
     status.add_argument("--project-id")