@topy-ai/maggie 0.7.53 → 0.7.54

package/bundled-skills/maggie-content-localization/SKILL.md

@@ -70,6 +70,32 @@ Norwegian, Finnish, Greek, Hebrew, Czech, Romanian, Hungarian, Thai, Persian,
 and Swahili. Use BCP 47 regions such as `es-MX`, `pt-BR`, `ar-SA`, or `ja-JP`
 when market-specific copy is required.
 
+## Text keys are site-wide; generated pages need position keys
+
+A translation stored under its source text (a text hash) applies to **every
+page** that shows that text. That is right for a shared header and wrong for
+generic phrases on generated pages: "your practice" is 诊所 on a dental page
+and 事务所 on an accountants page, and only one translation can exist per
+text. For generated or templated pages (one page per industry, city or
+product), render the source page, then store each node's translation under a
+**per-page position key** (page + node position, with the source text hash so
+a changed source shows as stale). Keep text keys only as a fallback for text
+that is genuinely the same everywhere.
+
+```bash
+maggie localization key-check rows.json [--locale zh-hans]
+maggie localization fragments --html dist --brand "Maggie"
+```
+
+`key-check` reads per-page rows (`page`, `position`, `text`, `translation`)
+and lists source texts translated differently on different pages — each one
+needs position keys. `fragments` reads rendered HTML and lists text split
+around an inline brand span into one- or two-word pieces ("Can", "No.",
+"What") that cannot be translated alone; translate the whole sentence with
+the span as a placeholder instead. Agents writing in parallel must use one
+glossary for short shared fragments, or the same piece gets different
+translations from different writers.
+
 ## Email and lifecycle email
 
 Localized email is a content surface with its own checks. Resolve the

package/bundled-skills/maggie-dash/SKILL.md

@@ -31,9 +31,35 @@ must already be configured for the project owner.
 maggie dash install --project . --confirm
 ```
 
+This installs **only the core**: the dashboard, the auth boundary
+(email/password sign-in, first-owner registration, password reset), the
+`/_maggie/admin` route, navigation and the core schema. It then reads the host
+(framework, existing sign-in, database, payments, whether the site sells
+services or publishes a blog, locales) and prints `recommendations`, one per
+optional module or companion skill with a reason. Install a module only after
+the user agrees:
+
+```bash
+maggie dash recommend --project .                 # analysis only, writes nothing
+maggie dash add booking --project . --confirm     # same as: maggie booking install --confirm
+```
+
+Booking is the optional code module MaggieDash ships (workspace, backend,
+schema, Stripe adapter, worker, env example). Blog, localization, social
+sharing and ops are Maggie skills that use the core panels; the
+recommendations name them. Never pass `--with booking` or `--all-modules` for
+a site that has not asked for bookings: a content-only site must not receive
+payment and booking files. A release without the module split (MaggieDash
+0.2.13 or older) still installs everything and says so in `notices`.
+
+Server settings in the Astro scaffold are read at run time
+(`src/lib/maggie/env.ts`). Never read a secret through `import.meta.env.X` in
+host code: Vite inlines it into the build output.
+
 The command is idempotent, preserves existing files unless `--force` is
-explicitly supplied, and records the resolved revision in
-`.maggie/dash-install.json`. It never accepts or stores a GitHub token as a
+explicitly supplied, and records the resolved revision and installed
+`modules` in `.maggie/dash-install.json` (a later `install` keeps refreshing
+modules that were added). It never accepts or stores a GitHub token as a
 CLI argument. For local development or a pinned checkout, use
 `--source /path/to/MaggieDash` or `--source URL --ref REF`.
 

package/bundled-skills/maggie-deployment/SKILL.md

@@ -25,6 +25,33 @@ metadata:
 - Product CLI and MCP packages: `maggie product release-check|smoke|mcp-check`
   ([product release](../maggie-assistant-tools/references/product-release.md)).
 
+## Downstream surfaces after a major product release
+
+A product change is not released while an agent-facing surface still
+describes the old product. After any major change to the app, the dashboard or
+the backend API (a new feature or channel, a renamed tab, a changed rule or
+limit), walk every surface below and either update it or record "no change":
+
+| Surface | Check | Evidence |
+|---|---|---|
+| Remote MCP tools | New or changed API params and response fields have tools; descriptions use the product's words | `tools/list` on the live server: count and the new names |
+| Agent system prompts | In-app assistant and any hosted bridge/agent prompt name tabs, channels and rules as the app does | One question about the change answered correctly |
+| Skills catalog and marketplace | Grep skills for the old wording; `mcp_tools` lists only real tool names; any tool-name allowlist is in sync with the tool source | Validator passes; marketplace repo pushed; agent hosts re-synced and recycled |
+| CLI and MCP npm packages | Commands/columns for the new data; both package versions bumped together | `npm view <pkg> version` |
+| Third-party plugins (ChatGPT, IDE) | Usually nothing if they use the remote MCP; re-review when tool names or auth change | Plugin lists the new tools |
+| SDK / API client types | New response fields typed | Workspace typecheck |
+| Mobile app | Web deploy plus OTA when the native fingerprint matches; a new build when it does not | Fingerprint compare; update id |
+| Assistant memory | A new channel or surface gets its own memory channel | Memory read for that channel |
+| Docs | PRD task list, progress log and the deployment runbook | — |
+| Preview host protection | Before (or after) adding basic auth to a preview host, every workflow, script or webhook that sends to it is repointed to production or sends the preview's basic-auth credentials from a secret — a bearer token does not pass basic auth | `maggie deployment preview-auth-check --host preview.example.com --repo . --live` passes; the next run of each listed workflow is green and the public surfaces it feeds show the new version |
+| npm staged publishes | A just-published version can stay invisible as `latest` for minutes; do not report it until it is. `Cannot publish over previously staged version` means the earlier attempt was already accepted, not a failure | `maggie product published --package-name NAME --version X --publish-log publish.log` reports `live` |
+
+Run the walk in the release order (schema → backend → dashboard → app →
+MCP/agent → bridge → npm → skills) and record which surfaces changed in the
+release record. Keep publish tokens in an env file and pass them through a
+temporary npmrc (`NPM_CONFIG_USERCONFIG`) that is deleted afterwards; never
+print them.
+
 ## Edge and rendered canary
 
 After staging or production deployment, verify that the edge serves the

package/bundled-skills/maggie-design/SKILL.md

@@ -262,6 +262,59 @@ maggie design step author-<id> --project . \
 An author plan is not complete until every `requiredSteps` entry has matching
 evidence and the explicit approval step is recorded.
 
+### Bulk author mode (many similar pages)
+
+For a family of similar pages (one use-case page per industry, one page per
+city), use one bulk job instead of hand-built scripts:
+
+```bash
+maggie design bulk plan --project . --targets targets.json --brief BRIEF.md --facts FACTS.md \
+  --validator '["python3", "scripts/validate-page.py"]' --check links --check prices --confirm
+maggie design bulk next <job> --stage write          # next batch (default 8) with each page's currentHash
+maggie design bulk record <job> --target ID --stage written --expect-hash HASH
+maggie design bulk validate <job>                    # project validator + built-in checks
+maggie design bulk next <job> --stage picture        # only pages validated and unchanged since
+maggie design bulk record <job> --target ID --stage pictured
+maggie design bulk status <job>
+maggie design bulk seed <job> --confirm              # only when every page passed
+```
+
+The job enforces what goes wrong in a parallel run: a picture is drawn only
+for a page that validated and has not changed since (a picture worker must
+never rewrite a page a writer is still editing); a writer records with the
+hash it read and is refused if the page changed meanwhile (re-read, re-apply,
+record again); changing the brief, facts or validator mid-run sends every
+earlier pass back to `revalidate`; nothing is seeded until all pages are
+validated and pictured. Built-in checks: every internal link points at a page
+of the job or a `--known-routes` entry, and every price appears in the facts
+file. The project validator checks structure, counts, facts and translation
+coverage. Share one glossary between writers for short repeated fragments
+(see maggie-content-localization, position keys).
+
+### Page pictures: choose the engine before a large run
+
+`maggie media generate` draws one picture with either engine; `maggie media
+engine-plan` states time and cost first. Show the plan and wait for a yes
+before a run of more than a handful of pictures.
+
+```bash
+maggie media engine-plan --count 510 --size 2400x1000 --gemini-unit-cost <price>
+maggie media generate --engine gemini --size 2400x1000 --prompt "..." --output hero.png --confirm
+maggie media generate --engine codex --image screen.png --prompt "Redraw as a clean step picture" --output step.png --confirm
+```
+
+| Engine | Billing | Speed (observed) | Reference pictures |
+|---|---|---|---|
+| `codex` | the ChatGPT plan's quota via the local `codex` CLI, no per-picture charge | about 75 s | yes (`--image`, before `--`) |
+| `gemini` | the project's own `GEMINI_API_KEY` (its Google account) | about 19 s at 2K | no |
+
+For 510 pictures that is hours versus minutes. Gemini takes the nearest
+aspect ratio and a size from the target (2400x1000 → 21:9 at 2K; 1K up to
+1300 px, 2K up to 2600 px, else 4K); crop to the exact size and convert to
+WebP afterwards. `engine-plan` leaves the Gemini cost empty until you pass
+`--gemini-unit-cost` from the current price list. Only transient Gemini
+errors (429, 5xx, network) are retried.
+
 ## Content UI initialization
 
 Use content UI initialization when `maggie-blog` or
@@ -398,6 +451,34 @@ repeated sheet and modal changes. Add `maggie design textinput-check`: a
 after collapsing; see the `chat-composer` pattern). `// maggie-allow-textinput`
 marks a reviewed exception.
 
+Closing a modal sheet is the third iOS-only trap. Closing a sheet and, in the
+same tick, showing a toast, refreshing or writing query data, navigating,
+opening another sheet, or changing what the closing sheet shows can leave the
+sheet's transparent window on top of the app: it looks fine but takes no
+touches until the app is killed. Close first, then do the rest once it has
+slid away:
+
+    export const SHEET_CLOSE_MS = 450;   // the slide-out duration
+    export function afterSheetCloses(fn: () => void) {
+      if (Platform.OS === "web") fn(); else setTimeout(fn, SHEET_CLOSE_MS);
+    }
+    // setSheet(null); afterSheetCloses(() => { toast(...); refresh(); });
+
+    maggie design sheet-check --project apps/app
+
+`sheet-check` finds closes (`setSheet(null)`, `setXOpen(false)`, `onClose()`,
+and the setter of any state used in a sheet's `open`/`visible` prop) followed
+in the same block by a toast, a refetch/invalidate/`setQueryData`,
+`router.*`/`*.open(…)` or another sheet opening; work inside
+`afterSheetCloses`, `setTimeout`, `requestAnimationFrame`, a local helper that
+wraps them, or after `await new Promise(r => setTimeout(r, …))` is deferred and
+passes. Errors fail the check. Warnings: a parent callback (`onDone()`) right
+after a close, and a sheet whose content reads the same state as its `open`
+prop (`open={Boolean(item)} title={item?.label}`), which empties the sheet
+while it slides away — keep a separate open flag. `// maggie-allow-sheet-close`
+marks a reviewed exception. Keep it with pressable-check, safe-area-check and
+textinput-check in the app's lint loop.
+
 ### Onboarding wizards
 
 Use one pattern for multi-step setup (brand, logo, voice, posting hours, and

package/bundled-skills/maggie-feedback/SKILL.md

@@ -223,10 +223,18 @@ leaving contradictory claims current.
 The CLI never submits automatically. After reviewing the draft:
 
 ```bash
-maggie feedback submit .maggie/feedback/<feedback-id>.json \
-  --endpoint https://feedback.noblox.app/api/feedback --confirm
+maggie feedback submit .maggie/feedback/<feedback-id>.json --confirm
 ```
 
+Without `--endpoint` the draft goes to `https://feedback.noblox.app/api/feedback`
+and, only when that host fails before storing it (no connection, timeout, or a
+5xx such as Cloudflare's 526), to `https://feedback.cmo.so/api/feedback`. Both
+accept the same contract and de-duplicate on `feedbackId`, so a retry never
+creates a second record. A 4xx is the host rejecting the draft and is not
+retried elsewhere. The saved `submission` records the `endpoint` that accepted
+the draft and any `failedEndpoints`. Repeat `--endpoint URL` to give your own
+ordered list. Do not hand-edit drafts to point at a different host.
+
 Only HTTPS endpoints are accepted. Project paths, file contents, secrets, and
 logs are excluded by default. `--allow-project-context` is an explicit opt-in;
 even then, send only a short public-safe context note. After submission, the

package/bundled-skills/maggie-marketplace/SKILL.md

@@ -231,7 +231,7 @@ imported by the server and every node script (town pages, sitemaps, maps) —
 never a copy. It parses UK post towns and US "City, ST", falls back to the
 town field plus the state from the ZIP prefix when a US profile saved only
 the street, keeps non-US places in a US market ("Kingston, Jamaica"), and
-gives a normalised search key so "moonlake" finds "Moon Lake Spa", ranked
+gives a normalised search key so "lakeview" finds "Lake View Spa", ranked
 exact → prefix → word prefix → contains. See [directory towns and
 search](references/directory-search.md) for the generated-column SQL.
 

package/bundled-skills/maggie-marketplace/references/directory-search.md

@@ -27,7 +27,7 @@ counts per town.
 
 ## Name search
 
-People type "moonlake" for "Moon Lake Spa". Compare a normalised key —
+People type "lakeview" for "Lake View Spa". Compare a normalised key —
 lower case, accents removed, letters and digits only (`searchKey`) — as well
 as the plain `ILIKE` match, and rank exact and prefix matches first
 (`nameMatchRank`). In Postgres keep the key in a generated column with an

package/bundled-skills/maggie-marketplace/references/directory.mjs

@@ -85,8 +85,8 @@ export function parseTown(address, market, locality, postcode) {
 }
 
 /**
- * Name search key: lower case, accents removed, letters and digits only, so "moonlake", "Moon-Lake" and
- * "Moon Lake Spa" meet. Store it in a generated column (see directory-search.md) and compare both forms.
+ * Name search key: lower case, accents removed, letters and digits only, so "lakeview", "Lake-View" and
+ * "Lake View Spa" meet. Store it in a generated column (see directory-search.md) and compare both forms.
  * @param {string | null | undefined} value
  */
 export const searchKey = (value) => (value || "").normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "");

package/bundled-skills/maggie-mobile-app/SKILL.md

@@ -129,6 +129,35 @@ always restores the working copies — checked by hash — even when a step
 fails. A mismatch with the build's own files means the change needs a new
 native build. `MAGGIE_MOBILE_EAS` overrides the `npx eas-cli` invocation.
 
+### Monorepos: publish only to a runtime an installed build has
+
+In a pnpm monorepo the fingerprint also hashes pnpm's virtual-store paths
+(`node_modules/.pnpm/<pkg>@<version>_<peer hash>`), so a dependency change in
+**any** workspace package (React added to the website) can move the app's
+runtime. `eas update` then publishes to a runtime no build has — silently.
+`ignorePaths` and `fileHookTransform` cannot fix it: `@expo/fingerprint` adds
+each native module folder by its real path. Keep the installed builds'
+runtimes in a file and publish through the guard:
+
+```json
+{"ios": [{"build": 7, "eas_build_id": "…", "runtime": "19d7a260e8e2…"}], "android": []}
+```
+
+```bash
+maggie mobile ota-guard --project . --app-dir apps/app --platform ios --runtimes scripts/ota-runtimes.json
+maggie mobile ota-guard … --publish --message "Fix copy" --confirm
+```
+
+It computes the fingerprint (`expo-updates fingerprint:generate`), refuses
+when no installed build has it — naming the two ways out (a native build, or
+publishing from a worktree with the build's lockfile and workspace file after a
+frozen install) — and with `--publish --confirm` runs `eas update` and checks
+that the published runtime is the one it checked. Add a build's runtime to the
+file when it ships; drop it when nobody runs it. At the next native build set
+an explicit `runtimeVersion` with a native-change check, so unrelated
+workspace changes cannot move it. `preflight` warns about a fingerprint
+runtime in a pnpm workspace.
+
 Show the plan's `costNotice` and wait for confirmation before step 1.
 
 ## 5. Store-review rules

package/bundled-skills/maggie-social-share/SKILL.md

@@ -36,6 +36,36 @@ URL, channel limits, UTM links, approval state, and provider post state.
   draft without `workspace_domain`. Apply the same rule in source selection:
   an account that manages several sites must not pick another site's
   articles for this workspace's plan.
+- **Live links only.** Before planning posts from articles, drop the ones
+  whose link is gone. A site that moved platforms leaves old URLs that answer
+  404; posts scheduled with them reach readers as dead links.
+
+  ```bash
+  maggie tool maggie_social_share.py link-check .maggie/candidate-articles.json
+  maggie tool maggie_social_share.py plan content.json --workspace-domain example.com --check-link
+  ```
+
+  Only a definite 404 or 410 (also after redirects) drops an article. Blocked
+  (403/429), failing (5xx) or unreachable pages are kept, so a firewall or an
+  outage cannot empty the list; verdicts are cached for 6 hours
+  (`.maggie/social-link-cache.json`, `--ttl-hours`). Prefer the URL the site
+  reports for a delivered post over an older stored one (maggie-blog, "Where a
+  delivered post went live").
+- **One picture per idea.** Posts written together for several channels from
+  one idea share one picture on every channel, and a later picture change
+  (redraw, replace, rewrite of an idea that had one) is applied to every
+  channel of that idea, not only some. Write all channels of an idea through
+  the same path — an article-sourced channel (often LinkedIn) must join the
+  other channels' idea instead of being written separately. Check with:
+
+  ```bash
+  maggie tool maggie_social_share.py pictures .maggie/social-drafts.json
+  ```
+
+  It groups drafts by `idea_id` and fails a group whose channels carry
+  different pictures or one without; a channel whose picture a person chose
+  records `image_source: "user"`. `validate` applies the same rule to the
+  channels of one draft.
 - **Image posts by default.** When a post has its own image (`image_url`),
   each channel gets `publish_mode: "image"` with the link in the text;
   `link_preview` is the default only without an image. A person may switch a

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")