@topy-ai/maggie 0.6.9 → 0.7.1

package/README.md

@@ -14,6 +14,16 @@ persistent project memory.
 
 ## Install
 
+`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
 ```
@@ -78,8 +88,9 @@ The CLI provides the installer plus durable workflow commands:
 maggie init | install | update | remove | list | doctor
 maggie cleanup --project . [--confirm]
 maggie bootstrap interview | phase ...
-maggie dash init | status | migrate
+maggie dash init | status | migrate | cms ...
 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
@@ -90,7 +101,7 @@ maggie localization ...          # plan, validate, review, publish, stale
 maggie service ...               # import, sync, generate, validate
 maggie seo performance ...       # sampled PageSpeed/CWV report and baseline
 maggie seo images ...             # inventory, variants, confirmation, validate
-maggie seo sitemap ...            # typed plan, validate, apply, rollback
+maggie seo sitemap ...            # typed/semantic plan, agent-files, apply, rollback
 maggie deployment | migration | release | analytics | schedule
 maggie deployment canary --asset URL=SHA256 --render-report report.json
 maggie design icon-inventory --source-dir src --runtime assets/icons.css
@@ -179,10 +190,25 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.6.9 update --project . --force
-npx @topy-ai/maggie@0.6.9 cleanup --project .
+npx @topy-ai/maggie@0.7.1 update --project . --force
+npx @topy-ai/maggie@0.7.1 cleanup --project .
 ```
 
+Maintainers should pass npm credentials through the repository helper, never
+as a command-line argument:
+
+```bash
+node scripts/publish-npm.mjs --maggie-env-file ../.env
+```
+
+The 0.7.1 workflow adds audited MaggieDash CMS operations (`cms revisions`,
+`trash`, `restore`, `schedule`, `duplicate`, `redirect`, and signed
+`preview`), import-authoritative service matching, shared translation indexes,
+sanitized seed manifests, lockfile/analytics traffic checks, semantic sitemap
+validation, locale-aware `llms.txt`/`sitemap.md`/`insights.md` generation,
+explicit integration states, and deployment Origin/infrastructure/data
+rollback gates.
+
 ## MaggieDash lifecycle
 
 For a new project, establish the local content and approval foundation before
@@ -419,6 +445,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/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|cms --project PATH [options]
   maggie dash status --project PATH
   maggie dash migrate --project PATH --confirm
   maggie content FILE --source PROVIDER --project PATH --confirm
@@ -92,7 +92,7 @@ Usage:
   maggie design author --project PATH --route /about --purpose TEXT --audience TEXT --confirm
   maggie auth reference --project PATH --confirm
   maggie auth check --project PATH [--production]
-  maggie blog init|inspect|ingest|validate|publish|sitemap|settings|rollback --project PATH
+  maggie blog init|inspect|ingest|validate|publish|sitemap|settings|rollback|integration-state
   maggie design status <job-id>
   maggie service import <provider-url> --project PATH
   maggie service sync <provider-url> --project PATH
@@ -106,15 +106,18 @@ Usage:
   maggie deployment canary --project PATH --asset URL=SHA256 --render-report report.json --output docs/deployment-canary.json
   maggie migration --project PATH --environment staging
   maggie schedule PATH/.maggie/schedule.json --project PATH
-  maggie analytics --project PATH --environment staging
+  maggie analytics [traffic-audit|release-gate] --project PATH --environment staging
   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 seo performance|images|sitemap [options]
+  maggie localization <extract|plan|generate|preview|validate|review|publish|stale|glossary> [options]
+  maggie seo performance|images|sitemap [options] (sitemap supports strict validate and agent-files)
   maggie feedback <collect|preview|submit|list> [options]
   maggie site-audit URL [--crawl] [--languages en-GB,es-MX,ja-JP] [--check-hreflang]
-  maggie ops audit --project PATH
+  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|preflight|verify|lockfiles|seed-manifest --project PATH
   maggie ops preflight --project PATH --write
 
 Examples:
@@ -287,7 +290,7 @@ function service(args) {
   const root = projectRoot(args);
   const script = join(root, "tools", "clis", "maggie_service_booking.py");
   if (!existsSync(script)) throw new Error(`service booking CLI is missing: ${script}`);
-  const result = spawnSync("python3", [script, ...args], { stdio: "inherit", cwd: root });
+  const result = spawnSync("python3", [script, ...args], { stdio: "inherit", cwd: root, env: { ...process.env, MAGGIE_VERSION: PACKAGE_VERSION } });
   if (result.error) throw result.error;
   process.exitCode = result.status ?? 1;
 }
@@ -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-references/maggiedash-dashboard-ui.md

@@ -0,0 +1,28 @@
+# MaggieDash dashboard UI contract
+
+MaggieDash workspaces use the lightweight contract in
+`templates/maggiedash/dashboard-ui-contract.json`. It is provider-neutral and
+describes the dashboard chrome, not a framework-specific component library.
+
+The reference is the users workspace: one `WorkspaceBar`, one sidebar/content
+navigation relationship, and one `ContentTabs` row. A route must not render a
+second horizontal navigation, duplicate its sidebar, or hide duplicate markup
+with CSS. `WorkspaceCard` owns card framing; page routes own content.
+
+`ContentTabs` accepts only the props it renders (`tabs`, `active`, `actions`,
+and `children`). It does not accept a page `title` or `description`. If a page
+needs a heading or description, render a dedicated page header or use
+`WorkspaceBar` explicitly. This keeps component APIs honest and prevents
+dead-copy drift.
+
+Validate a host implementation with:
+
+```bash
+maggie dash ui validate --contract templates/maggiedash/dashboard-ui-contract.json \
+  --source src/components/WorkspaceBar.tsx \
+  --source src/components/WorkspaceCard.tsx \
+  --source src/components/ContentTabs.tsx
+```
+
+The check is static evidence. It does not replace an authenticated browser
+review of the rendered dashboard at desktop and mobile sizes.

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
@@ -44,3 +60,15 @@ maggie design init --project . --surface blog \
 
 The blog skill supplies route/data semantics; `maggie-design` supplies the
 host-native components and responsive visual review.
+
+Optional Search Console/AI visibility integrations must report state rather
+than returning an ambiguous empty success payload. Use:
+
+```bash
+maggie blog integration-state                 # not-configured
+maggie blog integration-state --configured --consent-required  # awaiting-consent
+maggie blog integration-state --configured --authorized  # ready
+```
+
+Provider adapters should preserve the same `not-configured`,
+`awaiting-consent`, `awaiting-authorization`, `ready`, and `error` semantics.

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

@@ -7,6 +7,46 @@ metadata:
 
 # 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
@@ -76,3 +116,12 @@ styles, SVG, and dynamic expressions. Supplying source and render reports to
 remains backward-compatible without those artifacts. See
 [`docs/localization-extraction-render-prd.md`](../../docs/localization-extraction-render-prd.md)
 for the artifact contract and limitations.
+
+Use the shared translation index and route predicates from
+`tools/runtime/content_localization.py`. A host must not keep a second wording
+dictionary beside its translation registry: conflicting `(contentId, locale)`
+records fail closed. Use `is_translated_path()` for both exact routes and
+prefix routes, and do not let locale middleware capture root `.txt`, `.md`,
+`.xml`, or `.json` assets. If a framework rewrites a localized request,
+dedupe instrumentation with `rewrite_once(request_key, seen)` so one request
+does not count twice.

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.
 
@@ -43,3 +74,24 @@ not part of this skill.
 Before and after a meaningful run, load and record confirmed project
 preferences or repaired pitfalls with
 [the shared memory hook](../../references/memory-hook.md).
+
+CMS operations are explicit and auditable:
+
+```bash
+maggie dash cms revisions --project . --project-id local-project --document-id <id> --confirm
+maggie dash cms trash --project . --project-id local-project --document-id <id> --reason "remove from editor" --confirm
+maggie dash cms restore --project . --project-id local-project --document-id <id> --reason "restore" --confirm
+maggie dash cms schedule --project . --project-id local-project --document-id <id> \
+  --publish-at 2026-09-20T10:00:00Z --reason "approved release" --confirm
+maggie dash cms duplicate --project . --project-id local-project --document-id <id> \
+  --new-id <new-id> --new-slug <new-slug> --reason "create draft" --confirm
+maggie dash cms redirect --project . --project-id local-project --from-path /old --to-path /new \
+  --reason "canonical slug change" --confirm
+maggie dash cms preview --project . --project-id local-project --document-id <id> \
+  --secret "$MAGGIE_PREVIEW_SECRET" --confirm
+```
+
+Content writes create immutable revision snapshots. Trash is reversible and
+does not destroy the document. Scheduling is accepted only for approved
+content and requires a timezone. Preview tokens are short-lived HMAC-signed
+tokens; never place the secret in source control or generated reports.

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

@@ -210,3 +210,20 @@ Follow the shared [Maggie Decision Loop](../../references/decision-loop.md) for
 6. Require explicit final confirmation before any mutation or external write.
 
 If a decision is not relevant, record it as `skipped` with a reason. Do not silently assume a missing choice, and do not treat an existing output as permission to skip required work.
+
+For scheduled POST jobs, validate the request contract before installation:
+
+```bash
+maggie deployment --validate-request --method POST \
+  --origin https://example.test --has-auth
+maggie deployment --verify-infra --service fresha \
+  --units-dir .maggie/deployment/schedules
+```
+
+The deployment scheduler must send an explicit Origin and configured auth
+contract; a missing Origin must not be mistaken for an application auth
+failure. Infrastructure verification accepts a declared service/timer pair or
+both units being enabled in systemd. Data-dependent releases additionally
+require `rollback.backupId` and `rollback.restoreCommand` in
+`.maggie/deployment/data-release.json`, because switching code alone does not
+restore incompatible data.

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

@@ -7,6 +7,17 @@ metadata:
 
 # 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-ops/SKILL.md

@@ -7,6 +7,19 @@ metadata:
 
 # Maggie Ops
 
+Before release, run the lockfile guard when a project has more than one package
+manager:
+
+```bash
+maggie ops lockfiles --project .
+```
+
+It compares direct package and optional dependency names in `package.json`
+with `package-lock.json`, reports the presence of `pnpm-lock.yaml`, and fails
+when npm CI cannot install a declared package. It does not rewrite either
+lockfile; regenerate and commit both through the project's chosen package
+manager workflow.
+
 ## Automatic memory hook
 
 Follow [Maggie Memory Hook](../../references/memory-hook.md) at invocation and completion.
@@ -195,3 +208,17 @@ Follow the shared [Maggie Decision Loop](../../references/decision-loop.md) for
 6. Require explicit final confirmation before any mutation or external write.
 
 If a decision is not relevant, record it as `skipped` with a reason. Do not silently assume a missing choice, and do not treat an existing output as permission to skip required work.
+
+Before data-dependent checks, validate an explicit sanitized fixture manifest:
+
+```bash
+maggie ops seed-manifest --project . --manifest .maggie/seed-manifest.json
+maggie ops lockfiles --project .
+```
+
+The seed manifest must be opt-in, sanitized, and contain non-empty fixtures;
+an empty dev database is not evidence that an operational check passed.
+Known Maggie/toolchain traffic can be measured without polluting first-party
+analytics using `maggie analytics traffic-audit --events events.json`. The
+classifier excludes only explicit tool/test markers and never infers identity
+from IP or private fields.

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

@@ -7,6 +7,85 @@ metadata:
 
 # 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.
+`lastmod` must come from a recorded content-change event or source revision;
+never derive it from `updated_at`, pull time, sync time, or deployment time.
+If the change date is unknown, omit `lastmod`. An empty content-type does not
+need a sitemap chunk in the sitemap index; serving an empty endpoint and
+advertising it are separate decisions.
+
+## 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.
@@ -48,7 +127,7 @@ maggie seo sitemap rollback --backup-manifest .maggie-sitemap-backups/<plan>/bac
 
 Only confirmed image variants may enter `srcset`; `apply` requires an explicit
 confirmation and host adapter. Sitemap plans keep content types separate,
-emit chunk 1 for empty enabled types, enforce absolute same-origin URLs, and
+omit empty chunks from the sitemap index, enforce absolute same-origin URLs, and
 record redirects for removed sitemap files. Read the [image and sitemap PRD](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/docs/image-sitemap-structure-prd.md)
 for adapter and rollback rules.
 
@@ -133,3 +212,18 @@ Follow the shared [Maggie Decision Loop](../../references/decision-loop.md) for
 6. Require explicit final confirmation before any mutation or external write.
 
 If a decision is not relevant, record it as `skipped` with a reason. Do not silently assume a missing choice, and do not treat an existing output as permission to skip required work.
+
+Use semantic validation when route evidence is available:
+
+```bash
+maggie seo sitemap validate --plan .maggie/sitemap-plan.json --strict-semantic
+maggie seo sitemap agent-files --origin https://example.test \
+  --routes-file .maggie/routes.tsv --locale fr-FR --output-dir public/fr
+```
+
+Strict validation checks searchable content evidence, indexability, self
+canonical ownership and truthful `lastmod` provenance. `lastmod` may only be
+backed by a content-change/source-revision event; operational sync, pull,
+deploy, or `updated_at` timestamps are rejected. The agent-file command emits
+locale-aware `llms.txt`, `sitemap.md`, and `insights.md` from the same route
+inventory; non-indexable routes are omitted.

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

@@ -7,6 +7,22 @@ metadata:
 
 # Maggie Service Booking
 
+Route matching evidence must come from the route source's actual import
+statements. The shared resolver in `tools/runtime/route_imports.py` resolves
+relative imports and records a component fingerprint; it never selects a
+same-basename sibling as a fallback. Missing imports are evidence requiring
+review, not permission to guess.
+
+## 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-templates/maggiedash/README.md

@@ -7,3 +7,7 @@ own framework conventions for rendering.
 The package includes only these lightweight contracts. Large marketplace
 previews and template media remain separately distributable through the
 marketplace repository.
+
+Dashboard routes should adopt `dashboard-ui-contract.json` and validate their
+actual host components with `maggie dash ui validate`. The contract provides
+the shared workspace chrome and rejects components that declare dead props.