@topy-ai/maggie 0.6.8 → 0.7.0

package/README.md

@@ -14,6 +14,16 @@ persistent project memory.
 
 ## Install
 
+Working-tree additions (not yet released): `site-audit --crawl --save-baseline
+FILE --reviewer NAME` records a reviewed site contract; `site-audit --crawl
+--baseline FILE` fails on URL, metadata, HTML structure or copy changes.
+Complete sitemap coverage is required and existing baselines cannot be
+overwritten. This does not verify browser layout or source-only changes.
+
+`localization generate` invokes a trusted project-supplied provider process
+with explicit `--confirm`, resumable draft batches and no automatic publishing.
+See the installed localization skill for the adapter protocol and examples.
+
 ```bash
 npx @topy-ai/maggie init --agent codex
 ```
@@ -80,6 +90,7 @@ maggie cleanup --project . [--confirm]
 maggie bootstrap interview | phase ...
 maggie dash init | status | migrate
 maggie dash transition ...      # explicit content approval transition
+maggie dash variant ...         # service variant create/review/preview/publish
 maggie clone ...                 # authorized homepage capture
 maggie design ...                # authorized interior-page design
 maggie clone-to-template ...     # URL → validated marketplace template
@@ -179,8 +190,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.6.8 update --project . --force
-npx @topy-ai/maggie@0.6.8 cleanup --project .
+npx @topy-ai/maggie@0.7.0 update --project . --force
+npx @topy-ai/maggie@0.7.0 cleanup --project .
 ```
 
 ## MaggieDash lifecycle
@@ -419,6 +430,32 @@ Blog imports are idempotent and draft-first. Published slugs remain stable;
 public feeds exclude drafts, and `maggie blog rollback --confirm` restores the
 latest local content backup.
 
+In the working tree, opt-in blog translation uses `autoTranslateEnabled` and
+`translationLocales` in `.maggie/blog/settings.json`. Process or retry persisted
+posts without a new pull:
+
+```bash
+maggie blog translate-pending --project . \
+  --adapter-command '["python3", "scripts/translation-provider.py"]' --confirm
+```
+
+The project supplies the trusted provider script. Completed locale/revision
+tasks are skipped; failed work returns nonzero. Title, excerpt, body, topic
+labels and supplied image alt text remain draft/non-indexable. Run one worker
+per project; existing host HTTP schedulers require separate integration.
+
+Browser behavior validation uses the shared gstack browser:
+
+```bash
+maggie browser-audit https://example.com \
+  --browse "$HOME/.codex/skills/gstack/browse/dist/browse" \
+  --output .maggie/browser-audit --required main --sticky header \
+  --viewport 390x844 --viewport 768x1024
+```
+
+It captures scroll/geometry samples and screenshots, then fails on hidden
+required elements, horizontal overflow or invalid sticky positioning.
+
 List every installed skill and command:
 
 ```bash

package/README.zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.6.8 init --agent all
+npx @topy-ai/maggie@0.6.9 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 

package/bin/maggie.js

@@ -65,7 +65,7 @@ Usage:
   maggie list
   maggie doctor [--project PATH]
   maggie bootstrap interview [project]
-  maggie dash init --project PATH --confirm
+  maggie dash init|status|migrate|transition|variant --project PATH [options]
   maggie dash status --project PATH
   maggie dash migrate --project PATH --confirm
   maggie content FILE --source PROVIDER --project PATH --confirm
@@ -110,10 +110,13 @@ Usage:
   maggie release PATH --environment staging --target vps-with-cloudflare-dns
   maggie api lifecycle --project PATH [--execute --allow-quota]
   maggie memory <init|list|search|context|add|record-error|transition|export> --project PATH
-  maggie localization <plan|preview|validate|review|publish|stale|glossary> [options]
+  maggie localization <extract|plan|generate|preview|validate|review|publish|stale|glossary> [options]
   maggie seo performance|images|sitemap [options]
   maggie feedback <collect|preview|submit|list> [options]
   maggie site-audit URL [--crawl] [--languages en-GB,es-MX,ja-JP] [--check-hreflang]
+  maggie site-audit URL --crawl --save-baseline FILE --reviewer NAME
+  maggie site-audit URL --crawl --baseline FILE
+  maggie browser-audit URL --browse PATH --output DIR --required SELECTOR [--sticky SELECTOR]
   maggie ops audit --project PATH
   maggie ops preflight --project PATH --write
 
@@ -390,6 +393,7 @@ try {
   else if (command === "localization") workflowCli("maggie_localization.py", args);
   else if (command === "feedback") workflowCli("maggie_feedback.py", args);
   else if (command === "site-audit") workflowCli("site_audit.py", args);
+  else if (command === "browser-audit") workflowCli("maggie_browser_audit.py", args);
   else if (command === "dash") workflowCli("maggie_dash.py", args);
   else if (command === "content") workflowCli("maggie_content.py", args);
   else if (command === "init" || command === "install") install(args);

package/bundled-references/blog-translation-ingestion.md

@@ -0,0 +1,52 @@
+# Blog translation ingestion contract
+
+## Entry points and ownership
+
+List every ingest entry point before enabling automatic translation: manual
+CLI, admin HTTP action, scheduled tick, webhook and backfill. Each must use
+the same post-persistence scheduling function. Record the caller and source
+revision in the run evidence. A hook in a standalone script is insufficient
+evidence for a scheduled HTTP path.
+
+The packaged Python BlogStore reconciles durable translation tasks after source
+persistence when `autoTranslateEnabled` is true and `translationLocales` contains
+supported locale tags. The same reconciliation runs before translation retries,
+so an interruption between source persistence and scheduling is recoverable.
+Tasks are under `.maggie/blog/translations/`; content changes create new task
+identities, and only current identities are processed. Old drafts are retained
+for inspection, not eligible for automatic publication.
+
+Run `maggie blog translate-pending --project . --adapter-command
+'["python3", "scripts/translation-provider.py"]' --confirm` to generate drafts
+from saved sources without re-pulling. The project supplies a trusted adapter
+using the localization provider protocol. It receives title, excerpt, body,
+topic labels and supplied image alt text. Completed tasks are skipped; failures
+return partial/nonzero and store only an error category. Use one worker per
+project. Host database/API schedulers must explicitly integrate this boundary;
+installing the skill does not patch an existing host ingestion implementation.
+
+## Durable work
+
+After source persistence, enqueue translation work using an idempotency key
+of project, content ID, source revision, target locale and operation. The
+source write and scheduling intent must commit together or use a reconciliation
+pass that detects missing intents. A repeat pull must retry pending/failed
+translation without purchasing another upstream pull or duplicating completed
+work. A changed source revision invalidates earlier translation work.
+
+Track pending, running, succeeded and failed states with attempt count and
+safe error category. A run with failed required translations is partial, not
+completed. Missing credentials or provider availability must be visible;
+never print credentials or provider payloads in the report. Keep translated
+content draft and non-indexable until its validation and review pass.
+
+## Acceptance evidence
+
+Exercise the actual CLI and scheduled HTTP entry points against fixture
+providers. With translation enabled, both must schedule identical work for
+the same source revision. With translation disabled, neither schedules work.
+Test provider failure, process interruption, retry without re-pull, duplicate
+delivery, changed source revision, multiple target locales, media alt text and
+topic labels. Assert persisted target output and queue state, not merely the
+presence of a translate function name. Browser preview must show the target
+locale before publication is claimed complete.

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

@@ -11,6 +11,22 @@ project lessons, never raw provider credentials or temporary content facts.
 
 # Maggie Blog
 
+## Automatic translation across ingest paths
+
+Follow the [translation ingestion contract](../../references/blog-translation-ingestion.md)
+when adding host auto-translation. Inventory manual CLI, admin API and scheduler
+entry points and connect each to the same durable translation scheduling step.
+Verify the actual scheduled path with a fixture provider and failure/retry
+tests. An enabled setting or successful manual run does not prove scheduled
+translation works. Packaged BlogStore reconciles translation tasks when settings
+enable `autoTranslateEnabled` with supported `translationLocales`. Run
+`maggie blog translate-pending --project . --adapter-command
+'["python3", "scripts/translation-provider.py"]' --confirm` with a trusted
+project-supplied adapter to process saved posts without re-pulling. Completed
+locale/revision tasks are skipped; failed tasks retry from checkpoints. Run one
+worker per project. Outputs stay draft and non-indexable. Existing host HTTP
+and scheduler integrations still need separate implementation and tests.
+
 Use the stable CLI to initialize a local blog contract, ingest versioned local
 content, validate lifecycle invariants, publish with an actor and reason, and
 generate route/feed artifacts. Read the host framework and database contract

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

@@ -2,11 +2,51 @@
 name: maggie-content-localization
 description: Manage translation, polish, rewrite, market localization, review, stale detection, and publishing for pages, guides, posts, services, products, and categories.
 metadata:
-  version: 1.2.0
+  version: 1.3.0
 ---
 
 # Maggie Content Localization
 
+## Generation responsibility and operation contract
+
+`plan` records `generationContract.mode`, `preserveMeaning`,
+`allowStructuralRewrite`, and `marketAdaptation`. Rewrite permits structural
+changes; translate and polish preserve meaning; localise enables market
+adaptation. A host generation adapter or the authoring agent must apply these
+instructions when producing copy. Planning does not invoke a model or generate
+translations. Validation currently checks mode consistency and rewrite
+permission, not whether prose was actually restructured. Review the produced
+copy against the requested operation before approval.
+
+### Resumable draft generation
+
+After extracting source strings and planning a job with `--source`, run:
+
+```bash
+maggie localization generate .maggie/localization/<job>.json \
+  --project . --source .maggie/localization/source.json \
+  --output .maggie/localization/generation/<job>.json \
+  --adapter-command '["python3", "scripts/translation-provider.py"]' --confirm
+```
+
+The adapter script is project-supplied, not bundled. Only execute a trusted
+adapter: it receives source text and may call a paid external provider.
+The JSON argv array executes without a shell, relative to `--project`.
+Its stdin is a `maggie-provider-request.v1` object with `strings` and `contract`
+(job identity, source revision, languages, locale, market and operation).
+Its stdout must contain only a JSON object mapping every supplied string ID
+to nonempty translated text. Exit nonzero on provider failure; provider logs
+are suppressed from CLI errors to avoid exposing content or credentials.
+
+`--character-budget` defaults to 8000 source characters per batch (a single
+larger string remains intact); `--timeout` defaults to 120 seconds per call.
+Malformed output splits batches until individual strings; provider failures
+save completed batches for retry. Rerun with the same output to resume; changed
+source or operation requires a new output. Run only one process per output.
+The output is a draft checkpoint, not an approved translation: this command
+does not edit project files, update the job, publish, or prove semantic quality.
+Host ingestion integration and operation-quality verification remain under #28.
+
 Localization job filenames are derived from content identity, but content IDs
 are data, not paths. The CLI sanitizes separators and adds a short identity
 hash when needed, so IDs such as `site.example/static-pages` always produce a

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

@@ -33,6 +33,37 @@ Valid transitions and statuses are owned by the MaggieDash storage contract;
 do not edit the database directly. A transition is an auditable state change,
 not a publish shortcut.
 
+## Service variants
+
+Service variants use `.maggie/service-variants.json` so location, event and
+holiday pages retain service identity and canonical ownership:
+
+```bash
+maggie dash variant create --project . --service-id massage \
+  --variant-id massage-london --variant-type location --locale en-GB --market uk \
+  --slug location/london --title "Massage in London" \
+  --facts '[{"key":"availability","value":"Weekdays"}]' \
+  --source-revision source-1 --confirm
+maggie dash variant review --project . --variant-id massage-london \
+  --actor editor --reason "facts checked" --confirm
+maggie dash variant preview --project . --variant-id massage-london \
+  --actor reviewer --reason "rendered QA" --preview-url http://localhost/preview --confirm
+maggie dash variant publish --project . --variant-id massage-london \
+  --actor owner --reason "approved" --confirm
+```
+
+The lifecycle is draft → review → approved → preview/published. Records carry
+locale, market, source revision, provenance, canonical relationship, cluster
+links, hreflang, facts and layout family. Translated variants cannot publish
+before their canonical source. Slugs use `location/<slug>`, `event/<slug>`, or
+`holiday/<slug>`; collisions fail. `variant slug-plan` creates a reviewed
+redirect with owner approval before an indexed URL changes. `variant validate`
+checks facts, canonical relation, source similarity and layout metadata.
+With `--render-report report.json`, it additionally requires schema
+`maggie-service-variant-render.v1`, a passing report, and matching layout
+family, locale and canonical URL. Metadata validation alone is not a rendering
+claim.
+
 All mutating commands require `--confirm`. The default development adapter is
 SQLite; production adapters must satisfy the same versioned contracts.
 

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

@@ -2,7 +2,7 @@
 name: maggie-deployment
 description: Deploy and operate Maggie blog projects with Cloudflare Workers as the default target, while preserving an adapter boundary for VPS, GCP, and AWS.
 metadata:
-  version: 1.2.0
+  version: 1.3.0
 ---
 
 # Maggie Deployment

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

@@ -2,11 +2,22 @@
 name: maggie-design
 description: Design authorized interior pages, review rendered responsive layouts, or explicitly rebrand a packaged homepage/template. Use rebrand only with a named source brand and target brand.
 metadata:
-  version: 1.3.0
+  version: 1.4.0
 ---
 
 # Maggie Design
 
+## In-place route evidence
+
+`maggie design in-place --project . --route /example` resolves local source
+files and falls back to a discovered `[...slug]`/`[[...slug]]` file. That
+fallback is currently a source candidate, not proof that the concrete URL is
+served. Verify the route's HTTP response, content identity and framework route
+mapping before editing a shared catch-all. Next app-router catch-alls whose
+file is named `page.tsx` are not covered by this filename fallback. Capture
+responsive and interaction evidence separately; a plan in phase `ready` is
+not a successful browser test.
+
 ## Source-to-runtime icon inventory
 
 Before release, inventory icon names in source and compare them with the

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

@@ -38,6 +38,13 @@ truth, content state, or audit log.
 
 ## Commands
 
+`add` defaults to `candidate` and reports that the item is excluded from
+`search` and `context`. Inspect it with `maggie memory list --status candidate
+--project .`; after review, run `maggie memory transition --project . <kind>
+<id> active`. Explicit status listing supports query and skill filters while
+preserving project scope. Expired active items remain inspectable through
+explicit status listing but are excluded from normal context.
+
 ```bash
 maggie memory init --project .
 maggie memory context --project . --skill maggie-clone

package/bundled-skills/maggie-seo-geo/SKILL.md

@@ -2,11 +2,85 @@
 name: maggie-seo-geo
 description: Plan, audit, create, rewrite, and measure content for AI CMO's paid SEO and GEO workflow. Use for topic opportunities, AI visibility, technical SEO, extractable article structure, sitemap-based rewrites, GSC readback, or SEO/GEO client reports.
 metadata:
-  version: 1.0.0
+  version: 1.1.0
 ---
 
 # Maggie SEO and GEO
 
+## Static audit and sitemap evidence
+
+Run `maggie site-audit https://example.com --crawl --json` for sitemap-listed
+pages. Homepage checks expose `robots_directive` and `robots_conflict`.
+Crawl entries expose `robots` (no restrictive meta found) and
+`robots_conflict` (a contradiction exists). Missing robots meta is allowed;
+noindex/none/nofollow or contradictory index/follow directives fail the gate.
+Crawled pages also inspect X-Robots-Tag headers, including bot-prefixed noindex.
+Static audit success
+does not establish Google indexing, scroll behavior, responsive visibility,
+or translation quality. Record those as unverified without separate evidence.
+
+Crawl reports include `summary.byLocaleTemplate` with total, passed, failed
+and failed URLs per declared locale and template. Regions/scripts remain
+distinct (for example en-GB versus en-US). A template is identified only when
+the page has exactly one distinct `data-template` value; absent or ambiguous
+markup is `unknown`, not an inferred route family. Static report evidence marks
+`rendered` and `behavioral` as `not_run`; these groups do not prove responsive
+or scroll behavior. Fetch failures remain visible in the unknown group.
+
+Sitemap planning accepts TSV columns: content type, absolute URL, optional
+lastmod, optional JSON object mapping locale tags to alternate URLs, such as
+`{"en-GB":"https://example.com/post","zh-Hant":"https://example.com/zh/post"}`.
+It emits `lastmod` and `xhtml:link rel="alternate"`. Supply truthful content
+change dates; omit unknown dates. Alternates must currently use the approved
+origin. Reciprocal locale coverage and date semantics require separate review.
+
+## Freeze and compare a reviewed site
+
+```bash
+maggie site-audit https://example.com --crawl --json \
+  --save-baseline docs/seo-baseline-v1.json --reviewer maintainer
+maggie site-audit https://example.com --crawl --json \
+  --baseline docs/seo-baseline-v1.json --output .maggie/seo-comparison.json
+```
+
+Only save after reviewing the launched site. Creation requires a passing,
+complete sitemap crawl and never overwrites an existing file. Comparison exits
+nonzero for added/removed URLs, changed metadata, response directives/redirect
+targets, structured data, images, DOM structure or text. Text and structure
+hashes catch served translation reversions and template swaps even when section
+counts match. Reports list changed fields, not raw copy.
+
+A crawl exceeding `--max-pages` fails instead of silently sampling; raise the
+limit to cover the sitemap. Oversized responses fail instead of truncating.
+For intentional changes, review the diff and create a new versioned baseline
+with a reviewer. Commit the approved change and new contract together; never
+automatically replace the baseline following failure. Dynamic dates, class
+names and copy can produce legitimate differences requiring review.
+
+This covers server-rendered sitemap pages, not CSS rendering, JavaScript-only
+content, database translation keys or browser interactions. A source key change
+is detected here only when it changes served content. Baselines contain site
+metadata; do not publish private project contracts without permission.
+
+## Browser behavior evidence
+
+For a local or deployed page, run the browser audit with the shared gstack
+`browse` binary:
+
+```bash
+maggie browser-audit https://example.com --browse "$HOME/.codex/skills/gstack/browse/dist/browse" \
+  --output .maggie/browser-audit --required "main" \
+  --required "nav" --sticky "header" --viewport 390x844 --viewport 768x1024
+```
+
+The command captures three real scroll positions per viewport, DOM geometry,
+horizontal overflow, required-element visibility, sticky/fixed top-inset
+behavior and a screenshot. It exits nonzero for missing/hidden elements, mixed
+viewport samples, no scroll advance, overflow or sticky geometry failure. It
+does not claim keyboard accessibility, network asset correctness or semantic
+content quality unless those checks run separately. Use the installed browser
+path explicitly when Bun is not in PATH.
+
 ## Automatic memory hook
 
 Follow [Maggie Memory Hook](../../references/memory-hook.md) at invocation and completion.

package/bundled-skills/maggie-service-booking/SKILL.md

@@ -2,11 +2,21 @@
 name: maggie-service-booking
 description: Import, synchronise, validate, and design SPA service pages from a booking provider such as Fresha. Use for service catalogues, treatment variants, prices, durations, booking links, payment links, and booking-aware page generation.
 metadata:
-  version: 1.0.0
+  version: 1.1.0
 ---
 
 # Maggie Service Booking
 
+## Reviewed page relationships
+
+Reviewed page selection preserves existing `supporting` relations, including
+routes absent from the current source scan. It does not automatically create
+supporting relations for all suggested candidates. Inspect each service's
+`pages` after selection and validate the rendered links. The current selection
+path writes `canonical` for selected pages; multiple selections can violate
+the one-canonical invariant. Resolve roles and run validation before publishing.
+Variant role assignment and layout/URL conventions remain tracked in issue #27.
+
 ## Automatic memory hook
 
 Follow [Maggie Memory Hook](../../references/memory-hook.md) at invocation and completion.

package/bundled-tools/clis/maggie_blog.py

@@ -10,11 +10,18 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
 from maggie_blog import BlogStore  # noqa: E402
+from localization_runner import process_adapter
 
 
 def main() -> int:
     parser = argparse.ArgumentParser(prog="maggie blog")
     sub = parser.add_subparsers(dest="command", required=True)
+    translate = sub.add_parser("translate-pending")
+    translate.add_argument("--project", type=Path, default=Path.cwd())
+    translate.add_argument("--adapter-command", required=True, help="trusted provider JSON argv array")
+    translate.add_argument("--timeout", type=int, default=120)
+    translate.add_argument("--character-budget", type=int, default=8000)
+    translate.add_argument("--confirm", action="store_true")
     init = sub.add_parser("init"); init.add_argument("--project", type=Path, default=Path.cwd()); init.add_argument("--base-path", default="/our-blogs"); init.add_argument("--posts-per-page", type=int, default=9); init.add_argument("--confirm", action="store_true")
     inspect = sub.add_parser("inspect"); inspect.add_argument("--project", type=Path, default=Path.cwd())
     ingest = sub.add_parser("ingest"); ingest.add_argument("--project", type=Path, default=Path.cwd()); ingest.add_argument("--input", type=Path, required=True); ingest.add_argument("--source", default="local"); ingest.add_argument("--confirm", action="store_true")
@@ -25,10 +32,13 @@ def main() -> int:
     rollback = sub.add_parser("rollback"); rollback.add_argument("--project", type=Path, default=Path.cwd()); rollback.add_argument("--backup"); rollback.add_argument("--confirm", action="store_true")
     args = parser.parse_args()
     store = BlogStore(args.project.resolve())
-    if args.command in {"init", "ingest", "publish", "rollback"} and not args.confirm:
+    if args.command in {"init", "ingest", "publish", "rollback", "translate-pending"} and not args.confirm:
         print("CONFIRMATION_REQUIRED: rerun with --confirm", file=sys.stderr); return 2
     try:
         if args.command == "init": result = store.init(args.base_path, args.posts_per_page)
+        elif args.command == "translate-pending":
+            adapter = process_adapter(json.loads(args.adapter_command), args.project, args.timeout)
+            result = store.translate_pending(adapter, args.character_budget)
         elif args.command == "inspect": result = {"settings": store.settings(), "posts": store.posts(), "runs": json.loads(store.runs_path.read_text(encoding="utf-8")) if store.runs_path.exists() else []}
         elif args.command == "ingest":
             payload = json.loads(args.input.read_text(encoding="utf-8"));
@@ -42,6 +52,8 @@ def main() -> int:
     except (OSError, ValueError, json.JSONDecodeError) as error:
         print(f"maggie-blog: {error}", file=sys.stderr); return 1
     print(json.dumps(result, indent=2, ensure_ascii=False))
+    if args.command in {"ingest", "translate-pending"} and result.get("status") == "partial":
+        return 1
     return 0 if args.command != "validate" or result.get("valid") else 1
 
 

package/bundled-tools/clis/maggie_browser_audit.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Capture real viewport/scroll evidence using an installed gstack browse CLI."""
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+from urllib.parse import urlparse
+
+RUNTIME = Path(__file__).resolve().parents[1] / "runtime"
+sys.path.insert(0, str(RUNTIME))
+from browser_behavior import validate_samples
+from localization_runner import checkpoint
+
+
+def audit(args):
+    if urlparse(args.url).scheme not in {"http", "https", "file"}:
+        raise ValueError("URL must use http, https or file")
+    if not args.required:
+        raise ValueError("at least one --required selector is necessary")
+    output = args.output.resolve()
+    output.mkdir(parents=True, exist_ok=True)
+    def call(*command):
+        result = subprocess.run([str(args.browse), *command], capture_output=True, text=True, timeout=45)
+        if result.returncode:
+            raise ValueError("browser command failed: " + command[0])
+        return result.stdout
+    report = {"schemaVersion": "maggie-browser-audit.v1", "url": args.url,
+              "passed": False, "viewports": [], "evidence": "browser-captured"}
+    try:
+        for index, viewport in enumerate(args.viewport or ["390x844", "768x1024", "1440x900"]):
+            width, height = [int(value) for value in viewport.split("x")]
+            if min(width, height) < 100:
+                raise ValueError("viewport dimensions must be at least 100")
+            call("viewport", viewport)
+            call("goto", args.url)
+            selectors = list(dict.fromkeys(args.required + args.sticky))
+            call("js", "window.__maggieAuditSelectors=" + json.dumps(selectors))
+            samples = []
+            for step, fraction in enumerate([0, 0.5, 0.9]):
+                call("js", f"window.scrollTo(0, (document.documentElement.scrollHeight-innerHeight)*{fraction})")
+                # Two animation frames allow layout/scroll handlers to settle.
+                call("js", "new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(() => resolve(true))))")
+                sample = output / f"viewport-{index}-sample-{step}.json"
+                call("eval", str(RUNTIME / "browser_geometry.js"), "--out", str(sample), "--raw")
+                samples.append(json.loads(sample.read_text()))
+            screenshot = output / f"viewport-{index}.png"
+            call("screenshot", "--viewport", str(screenshot))
+            if not screenshot.is_file():
+                raise ValueError("browser did not create screenshot")
+            finding = validate_samples(samples, args.required, args.sticky)
+            report["viewports"].append({"viewport": viewport, "samples": samples,
+                "screenshot": str(screenshot), **finding})
+        report["passed"] = all(item["passed"] for item in report["viewports"])
+    finally:
+        checkpoint(output / "report.json", report)
+    print(json.dumps(report, indent=2))
+    return 0 if report["passed"] else 1
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("url")
+    parser.add_argument("--browse", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True, help="new directory for evidence")
+    parser.add_argument("--viewport", action="append")
+    parser.add_argument("--required", action="append", default=[])
+    parser.add_argument("--sticky", action="append", default=[])
+    args = parser.parse_args()
+    try:
+        return audit(args)
+    except (ValueError, OSError, subprocess.TimeoutExpired) as error:
+        print(f"browser-audit: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_dash.py

@@ -16,6 +16,7 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
 from maggie_dash_store import MaggieDashStore  # noqa: E402
+from service_variants import ServiceVariantStore  # noqa: E402
 
 
 def project_root(args: argparse.Namespace) -> Path:
@@ -92,6 +93,40 @@ def command_transition(args: argparse.Namespace) -> int:
         store.close()
 
 
+def variant_store(args: argparse.Namespace) -> ServiceVariantStore:
+    return ServiceVariantStore(project_root(args) / ".maggie" / "service-variants.json")
+
+
+def command_variant(args: argparse.Namespace) -> int:
+    require_confirm(args)
+    store = variant_store(args)
+    if args.variant_command == "create":
+        result = store.create(service_id=args.service_id, variant_id=args.variant_id,
+            variant_type=args.variant_type, locale=args.locale, market=args.market,
+            slug=args.slug, title=args.title, facts=json.loads(args.facts),
+            source_revision=args.source_revision, canonical_variant_id=args.canonical_variant_id,
+            cluster_links=args.cluster_link, layout_family=args.layout_family)
+    elif args.variant_command == "edit":
+        result = store.edit(args.variant_id, title=args.title, facts=json.loads(args.facts),
+            source_revision=args.source_revision, actor=args.actor, reason=args.reason)
+    elif args.variant_command == "translate":
+        result = store.translate(args.source_variant_id, variant_id=args.variant_id,
+            locale=args.locale, market=args.market, title=args.title, facts=json.loads(args.facts),
+            source_revision=args.source_revision, actor=args.actor)
+    elif args.variant_command in {"review", "preview", "publish", "archive"}:
+        target = {"review": "review", "preview": "preview", "publish": "published", "archive": "archived"}[args.variant_command]
+        result = store.transition(args.variant_id, target, args.actor, args.reason, preview_url=getattr(args, "preview_url", None))
+    elif args.variant_command == "validate":
+        render_report = json.loads(Path(args.render_report).read_text(encoding="utf-8")) if args.render_report else None
+        result = store.validate(args.variant_id, args.source_text, render_report)
+    elif args.variant_command == "slug-plan":
+        result = store.plan_slug_change(args.variant_id, args.new_slug, args.actor)
+    else:
+        result = [item for item in store.data["variants"] if not args.variant_id or item["id"] == args.variant_id]
+    emit(result)
+    return 0 if not isinstance(result, dict) or result.get("passed", True) else 1
+
+
 def parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="maggie dash", description=__doc__)
     sub = parser.add_subparsers(dest="command", required=True)
@@ -120,6 +155,18 @@ def parser() -> argparse.ArgumentParser:
     transition.add_argument("--reason", required=True)
     transition.add_argument("--confirm", action="store_true")
     transition.set_defaults(func=command_transition)
+    variant = sub.add_parser("variant", help="manage service variant lifecycle")
+    variant_sub = variant.add_subparsers(dest="variant_command", required=True)
+    create = variant_sub.add_parser("create"); create.add_argument("--project", default="."); create.add_argument("--service-id", required=True); create.add_argument("--variant-id", required=True); create.add_argument("--variant-type", required=True); create.add_argument("--locale", required=True); create.add_argument("--market", required=True); create.add_argument("--slug", required=True); create.add_argument("--title", required=True); create.add_argument("--facts", required=True); create.add_argument("--source-revision", required=True); create.add_argument("--canonical-variant-id"); create.add_argument("--cluster-link", action="append", default=[]); create.add_argument("--layout-family", default="service-default"); create.add_argument("--confirm", action="store_true")
+    edit = variant_sub.add_parser("edit"); edit.add_argument("--project", default="."); edit.add_argument("--variant-id", required=True); edit.add_argument("--title", required=True); edit.add_argument("--facts", required=True); edit.add_argument("--source-revision", required=True); edit.add_argument("--actor", required=True); edit.add_argument("--reason", required=True); edit.add_argument("--confirm", action="store_true")
+    translate = variant_sub.add_parser("translate"); translate.add_argument("--project", default="."); translate.add_argument("--source-variant-id", required=True); translate.add_argument("--variant-id", required=True); translate.add_argument("--locale", required=True); translate.add_argument("--market", required=True); translate.add_argument("--title", required=True); translate.add_argument("--facts", required=True); translate.add_argument("--source-revision", required=True); translate.add_argument("--actor", required=True); translate.add_argument("--confirm", action="store_true")
+    for name in ("review", "preview", "publish", "archive"):
+        command = variant_sub.add_parser(name); command.add_argument("--project", default="."); command.add_argument("--variant-id", required=True); command.add_argument("--actor", required=True); command.add_argument("--reason", required=True); command.add_argument("--confirm", action="store_true")
+        if name == "preview": command.add_argument("--preview-url", required=True)
+    validate = variant_sub.add_parser("validate"); validate.add_argument("--project", default="."); validate.add_argument("--variant-id", required=True); validate.add_argument("--source-text"); validate.add_argument("--render-report"); validate.add_argument("--confirm", action="store_true")
+    plan_slug = variant_sub.add_parser("slug-plan"); plan_slug.add_argument("--project", default="."); plan_slug.add_argument("--variant-id", required=True); plan_slug.add_argument("--new-slug", required=True); plan_slug.add_argument("--actor", required=True); plan_slug.add_argument("--confirm", action="store_true")
+    inspect = variant_sub.add_parser("inspect"); inspect.add_argument("--project", default="."); inspect.add_argument("--variant-id"); inspect.add_argument("--confirm", action="store_true")
+    variant.set_defaults(func=command_variant)
     return parser