@aiguru/google-web-operations 0.6.4

package/docs/PRODUCT-TECHNICAL-SPEC-v0.6.md

@@ -0,0 +1,98 @@
+# Google Web Operations: Product and Technical Specification v0.6
+
+Supersedes v0.5 (kept for history). v0.6 closes the roadmap that did not need a client's Tag Manager: rendered-page inspection with Playwright, a hosted worker (container image and built-in scheduler), Odoo product pages, and a pass over the human side of the package: `gwo doctor`, a grouped `gwo` help, a friendlier install, a Hebrew getting-started guide. The Tag Manager live validation waits for the first client container.
+
+## 1. Purpose
+
+Google Web Operations is an operational control layer for a portfolio of client websites. It observes technical health, search visibility, answer-engine readiness and measurement; turns observations into ranked findings; decides against playbooks; acts within a strict permission model; verifies every write; and records everything. It runs identically from Claude Code and Codex through one MCP server, and its sensing half runs on a schedule without any agent.
+
+## 2. Principles
+
+Unchanged from v0.2: one source of truth, host-neutral, observe before changing, policy before action, verify every write, auditability, no secret sprawl, background-capable, bounded output.
+
+New in v0.4: **a set of changes is reviewed as a set.** Where a write's effect is a bundle rather than one value (a container version), the operator's approval alone is not enough; the write also carries a token derived from the exact bundle that was shown (ADR-005).
+
+## 3. What v0.6 delivers (cumulative since v0.3)
+
+| Area | Delivered |
+|---|---|
+| Rendered checks | `web_inspect_rendered`: headless Chromium through Playwright (found in the package, the global npm root or `PLAYWRIGHT_PATH`; never a dependency), compared with the static HTML: word ratio, headings, JSON-LD and form fields that appear only after JavaScript; verdict server-rendered / partly-js / js-dependent with plain-language notes. Missing Playwright or browser produce the exact install command |
+| Hosted worker | `gwo worker loop` (daily and weekly at configured times in `TZ`, each run a child process with its exit code logged), `deploy/Dockerfile` and `deploy/compose.yml` (compiled package, state volume at `/home/gwo/.gwo`, AES token store), `docs/HOSTED-WORKER.md` with the token hand-over |
+| Odoo products | `product.template` addressed by `/shop/<slug>-<id>`: SEO fields and JSON-LD in `website_description`; category listings excluded |
+| Human side | `gwo doctor` (checklist with next steps; the same text rides in `ops_setup_status.rendered`), grouped `gwo` help, install output that says what to do next, `docs/GETTING-STARTED.he.md` |
+| Distribution | npm package `@aiguru/google-web-operations` on GitHub Packages (`npm i -g @aiguru/google-web-operations`, `gwo update` for the latest release; a token with read:packages once per machine) with the `gwo` executable: `gwo install [claude\|codex\|all]` writes the user-scope MCP server (absolute node and package paths), skills and slash commands for Claude Code (`~/.claude.json`, `~/.claude/skills`, `~/.claude/commands`) and the MCP block and skills for Codex (`~/.codex/config.toml`, `~/.codex/skills`); idempotent, `uninstall` removes only `gwo-*` entries. State in `GWO_HOME` (default `~/.gwo`: sites, .gwo-data, secrets, .env, optional policy); a checkout keeps state next to the code. The package ships compiled JavaScript (`tools/build-package.ts`, tsc with rewritten `.ts` imports) because Node does not strip types under `node_modules`; development stays native TypeScript. `npm run check` builds and runs the packaged bin. Release workflow packs a tarball on `v*` tags (ADR-006) |
+| Accessibility (IS 5568) | New `accessibility` rule area from static HTML (`packages/connectors/web-crawler/src/a11y.ts`): unlabelled form fields (high), unnamed buttons, empty and generic links, untitled iframes, blocked pinch zoom, skipped heading levels, positive tabindex, duplicate ids, autoplay media, missing main landmark, missing skip link; site-wide `a11y.statement.missing` (high, the Israeli legal requirement). Contrast, keyboard behaviour and PDFs are declared out of scope in the monthly playbook |
+| Tag Manager writes | Workspace creation under the policy prefix; `gtm_stage` writes tags, triggers and variables one verified write each (create, or merge-update by name; trigger names resolve to ids; triggers before tags); `gtm_workspace_diff` shapes GTM's own change list against the live version and derives a review token; `gtm_publish` syncs, re-checks the token, creates the version, publishes, verifies the live version id, and snapshots. `gtm_workspaces` shows staged and client-owned work |
+| Content writes | `content_set_title` (approval always, validated: 15 to 65 characters, one separator, no repeated term); `content_set_schema` (approval always, validated: schema.org context and type, FAQ shape, no script break, 20 KB cap; empty list removes); `site_page_schema` reads managed blocks next to what the live page emits |
+| Adapters | `readPageSchema` / `writePageSchema` on the adapter interface. Repository: `schema` array in the manifest entry. Odoo: one marked `<script type="application/ld+json" data-gwo="schema">` in the page view's arch (before `#wrap`, outside the editor-owned structure) or appended to a blog post's content; XML-safe serialisation; other scripts never touched |
+| Site decisions | `findings.suppress` in the site file: rule (exact or `area.*`), optional path (exact or prefix), reason. Applied after the rules run; suppressed findings are counted per rule in the scan header and audit log, never hidden. Added after the first developer review of a pilot site, where GA4-without-GTM and a short contact page were deliberate |
+| Setup from chat | `ops_setup_status` (one read: OAuth client, authorised account and scopes, write scopes, .env settings, per-site configuration and what is missing, next steps), `google_setup_oauth_client` (installs the downloaded Desktop-app JSON by path; contents never pass through chat), `google_auth_login` (consent flow from the host, waits ~90 s then continues in the background), `google_discover_apply`, `ops_add_site` (standard site file from url, name, platform), `ops_update_site` (dotted path, comments kept; site_id, policy and credentials refused), `ops_add_suppression`. All classed `auto` as this system's own configuration and recorded in the audit log. New `gwo-setup` skill and `/gwo-setup`, `/gwo-add-site` commands |
+| Client report | `report_client_monthly`: collects Search Console and GA4 totals for the month and the previous one, scan health now and a month ago, and the month's audit activity; composes the client document (Hebrew or English) per the report template with the agent's narrative on top; writes a .docx inside the company template (`GWO_DOCX_TEMPLATE`, header, footer and styles inherited, body replaced) or a standalone styled package, plus a Markdown twin. RTL by paragraph, run and table. Own OOXML writer over jszip; no other dependency |
+| Playbooks | New `gwo-measurement`: the standard stack per client, the audit, the stage-diff-publish protocol, entity bodies, key events, what to do when the client publishes. Weekly, daily, triage, onboarding and the content brief updated to name the new tools and their gates. Operating model gains a tools-by-intent table |
+| Hosts | Installed by `gwo install` from the generated `hosts/` tree; 10 skills and 9 commands (`/gwo-measure`, `/gwo-setup`, `/gwo-add-site` added) for Claude Code; the same 10 skills for Codex; both generated |
+| Quality | 92 tests: rendered comparison (a real browser when available), Odoo products, accessibility parsing and rules, path resolution and the installer against temporary homes, setup and registry administration, GTM pure helpers, suppressions, report composition (no jargon leaks), the Word writer standalone and inside the template, a fake Tag Manager API exercising blocked, staged, merged, stale-token and successful publish paths; title and schema validators and writes; Odoo arch injection and blog injection; repo schema round trip |
+
+Carried from v0.3 unchanged: OAuth with encrypted refresh token, Search Console, GA4, PageSpeed and Tag Manager reads, meta-description writes, key events, sitemap submission, pull requests, the scheduled worker with escalation and delivery, CI.
+
+## 4. Architecture
+
+```
+Claude Code ──┐
+              ├── apps/mcp-server ──┐
+Codex ────────┘                     │
+apps/worker (Task Scheduler) ───────┼── packages/core ── connectors/{web-crawler, google, odoo, repo, github, resend}
+apps/cli ───────────────────────────┘        ├── packages/policy
+                                             └── packages/storage
+packages/playbooks ── tools/build-hosts ──> hosts/claude, hosts/codex
+```
+
+`bin/gwo.js` dispatches to the MCP server, worker, installer or CLI. `packages/core/src/paths.ts` decides checkout versus installed layout. `packages/core/src/gtm-ops.ts` holds every Tag Manager operation, read and write; `content.ts` holds the three content writes and their validators; `report/monthly.ts` the client report; `connectors/docx` the Word writer. TypeScript executed natively by Node 22.18+. No build step. `tsc --noEmit` in CI.
+
+## 5. Operational loop
+
+```
+Observe -> Classify -> Authorise -> Execute -> Verify -> Record
+```
+
+Every write goes through `performWrite()`. A write whose verification fails is a failed write. Blocked attempts are recorded. For a container publish, "Authorise" is two tokens.
+
+## 6. Risk classes
+
+| Class | Gate |
+|---|---|
+| `auto` | none |
+| `approval_required` | token `<site_id>:<action>` in-session |
+| `approval_required` + review | the above plus the review token of the reviewed diff (`gtm.publish`) |
+| `protected` | never |
+
+`policies/default.yaml`; site overrides may only tighten. No policy ids were added in v0.4: `gtm.stage`, `gtm.publish`, `content.title.update` and `content.schema.update` were already listed and are now implemented.
+
+## 7. Schedules
+
+| Cadence | Pages | Worker does | Agent does |
+|---|---|---|---|
+| Daily 07:00 | 25 | scan, diff, escalate, report, deliver | triage anything escalated |
+| Weekly Monday 07:30 | 200 | scan, diff, escalate, report, deliver | the weekly improvement pass |
+| Monthly | 200 | on demand | deep scan and client report |
+
+Exit codes: 0 healthy, 2 escalations, 1 failures.
+
+## 8. Tool surface
+
+45 tools. Setup: `ops_setup_status`, `google_setup_oauth_client`, `google_auth_login`, `google_discover_apply`, `ops_add_site`, `ops_update_site`, `ops_add_suppression`. Reads: `report_client_monthly` (writes files under `.gwo-data`, not to any site), `ops_*`, `web_*`, `google_*`, `gsc_*`, `ga4_*`, `gtm_containers`, `gtm_versions`, `gtm_snapshot`, `gtm_diff`, `gtm_workspaces`, `gtm_workspace_diff`, `site_*`, `pagespeed_check`. Writes: `gsc_submit_sitemap`, `content_set_meta_description`, `content_set_title`, `content_set_schema`, `ga4_create_key_event`, `gtm_stage`, `gtm_publish`, `repo_open_pr`.
+
+## 9. Data model
+
+Under `GWO_HOME` (the checkout itself, or `~/.gwo`): `sites/<host>.yaml` and gitignored `<host>.secrets.yaml`; `.gwo-data/<site_id>/{latest-scan.json, snapshots/, gtm/, gtm-stage/, audit.jsonl}`; `.gwo-data/_runs/` for worker reports; `secrets/` for the OAuth client and token. `gtm-stage/` keeps each staging result with its diff and review token for the record; the gate itself recomputes from live state and never trusts the file.
+
+## 10. Security
+
+See `docs/SECURITY.md`. Additions in v0.4: Tag Manager edit and publish scopes are still opt-in (`auth login --scope gtm_edit`, `--scope gtm_publish`); the Odoo API user needs view-editing rights only for structured data, and the adapter edits one marked element; the review token is derived from server state and cannot be forged from a stale diff.
+
+## 11. Pilot status
+
+Both pilot sites are scanned daily and read live. Neither has a Tag Manager container registered yet (`google.tag_manager.public_id` is null), so the staged-write path is verified against a fake API and awaits a container. aiguru is being fixed by hand in parallel and is out of scope for agent writes this cycle. Pending on the operator: `analytics.edit` consent for the key-event write; `local_path` plus `gwo.seo.json` for content writes; Resend and GitHub tokens; a container id per site.
+
+## 12. v0.7 targets
+
+The first live Tag Manager cycle on a company-owned container, then on a client's; feedback from the first installs on other machines (Codex and a second Claude Code) folded into the setup skill; outcome metrics in the client report (clicks before and after each change); a tightened default policy profile for advisory-tier clients.

package/docs/SECURITY.md

@@ -0,0 +1,69 @@
+# Security model
+
+## Secrets
+
+Site registry files under `sites/` are non-secret configuration and are committed. Anything that grants access lives elsewhere:
+
+- `sites/<host>.secrets.yaml`: per-site credentials, today the Odoo API user and key. Gitignored. Merged at load time under a key the public view strips. The Odoo user is dedicated to this system, has Website editing rights only, and its key can be revoked in Odoo without touching anything else.
+- `.env`: `GOOGLE_ACCESS_TOKEN` (development only) and `GOOGLE_PAGESPEED_API_KEY`. Gitignored.
+- `secrets/`: reserved for the phase 2 encrypted refresh-token store. Gitignored.
+
+Tokens, keys and secrets must never appear in source control, prompts, tool outputs or audit payloads. `google_auth_status` reports which provider is active and never the token.
+
+## Google access
+
+One dedicated company Google account is added as a user to each client's Search Console, Analytics and Tag Manager. One identity, many properties. Clients grant access; they never share passwords.
+
+All Google calls go through a `TokenProvider`. Two implementations exist:
+
+**OAuth (durable, default when authorised).** `npm run cli -- auth login` runs an authorisation-code flow with PKCE against a "Desktop app" client (`secrets/oauth-client.json`), receives the redirect on a loopback port, and stores only the refresh token. Access tokens are refreshed on demand and kept in process memory. Storage at rest: DPAPI with CurrentUser scope on Windows (no key file exists), AES-256-GCM with a 0600 key file elsewhere. `auth status` reports account and scopes, never a token. `auth logout` deletes the record.
+
+Default scopes are the least that reads need: `webmasters` (Search Console read plus sitemap submit, which policy classes as `auto`), `analytics.readonly`, `tagmanager.readonly`, `openid`, `userinfo.email`. Write scopes are added deliberately, never by default:
+
+| Scope name | Google scope | Enables |
+|---|---|---|
+| `ga4_write` | `analytics.edit` | `ga4_create_key_event` |
+| `gtm_edit` | `tagmanager.edit.containers` | `gtm_stage` (workspaces and entities; nothing live) |
+| `gtm_publish` | `tagmanager.publish` | `gtm_publish` |
+
+`auth login --scope gtm_edit --scope gtm_publish` adds both. A write tool called without its scope fails with the exact command to run.
+
+**Env bridge (development only).** `GOOGLE_ACCESS_TOKEN` is a bearer token that expires in about an hour. Used only when no stored authorisation exists or `GWO_GOOGLE_AUTH=env` forces it.
+
+PageSpeed Insights does not need an OAuth scope, but calls are attributed to a project for quota. The connector sends the OAuth token so the calls count against our project rather than Google's shared keyless pool. `GOOGLE_PAGESPEED_API_KEY`, if set, takes precedence.
+
+Property discovery (`discover`) lists what the account can see and matches it to sites by host. It writes ids into `sites/*.yaml` only with `--apply`, and never writes credentials.
+
+## Setup from the chat
+
+The administration tools change this system's configuration only. The OAuth client is installed from a file path, so its contents never pass through a chat transcript. `ops_update_site` refuses any path that names a credential, `site_id`, or `policy`; site credentials are typed into `sites/<host>.secrets.yaml` by the operator, never into a tool call. `google_auth_login` opens the browser on the operator's machine; the consent happens there and only the encrypted refresh token is stored.
+
+## Writes
+
+Every mutating operation is classified before execution (`packages/policy`). `protected` actions are refused in code. `approval_required` actions need a token the operator produces in the same session. A host prompt cannot lower a class. Site overrides can only raise one.
+
+Every write records the value before, the value after, and whether a post-write read verified the change.
+
+Tag Manager writes always go to a workspace whose name carries the policy prefix (`gwo-`), never to the default workspace and never to one the client created. Publishing needs the approval token for `gtm.publish` and a review token derived from the exact set of staged changes and the live version id (ADR-005). The token is recomputed from GTM's own state inside the write, so a stale or invented token cannot publish. Deleting a workspace that holds changes, and deleting a container, are protected.
+
+Structured data written to a site is validated for shape (schema.org context and type, no `</script`, size cap) and placed in one marked element the system owns; the adapters never edit any other script on the page. The Odoo API user needs view-editing rights for this and nothing more.
+
+## PII
+
+Visitor form values, names, email addresses, phone numbers, message content and health information are never stored, forwarded or sent to analytics by this system. This matters especially for clients in health and personal services.
+
+## Logging
+
+For stdio MCP, stdout is reserved for protocol traffic. All diagnostics go to stderr. Audit records redact anything that looks like a credential.
+
+## Crawling
+
+The crawler identifies itself with a user agent that names the operator, respects a politeness delay, caps concurrency and pages per scan, and only crawls sites in the registry.
+
+## Delivery and pull requests
+
+RESEND_API_KEY sends run reports by email; the reports contain site health summaries, never credentials. GITHUB_TOKEN is a fine-grained token limited to Contents and Pull requests on the site repositories the company develops; it is used only by repo_open_pr, which is approval-gated. Both are environment variables and never stored in site files.
+
+## Scheduled runs
+
+The worker is registered in Windows Task Scheduler as the operator Windows user, because the Google token is DPAPI-bound to that user. It runs only when the machine is on and catches up a missed run at next start. A hosted worker with its own consent is a v0.6 target.

package/docs/SITE-ADAPTERS.md

@@ -0,0 +1,87 @@
+# Site write adapters
+
+How the agent changes a site itself, as opposed to changing Google's view of it. Every adapter exposes the same surface (`packages/core/src/adapters.ts`): `ping`, `listPages`, `readPageSeo`, `writePageSeo`, `readPageSchema`, `writePageSchema`. Write tools never call an adapter's write directly; they go through `performWrite()`, which reads before, writes, reads after and verifies.
+
+| Write | Tool | Policy |
+|---|---|---|
+| meta description | `content_set_meta_description` | `auto` when empty, `content.meta_description.update` otherwise |
+| title | `content_set_title` | `content.title.update`, always approval |
+| structured data | `content_set_schema` | `content.schema.update`, always approval |
+
+## Odoo (`write.adapter: odoo`)
+
+Transport: JSON-RPC to `<url>/jsonrpc`. Authentication: a dedicated API user with an API key, used as the RPC password. No browser session.
+
+Site file, non-secret:
+
+```yaml
+write:
+  adapter: odoo
+  odoo:
+    url: https://erp.client.co.il
+    db: client_prod
+    website_id: 1        # optional, for multi-website databases
+```
+
+Secrets file `sites/<host>.secrets.yaml` (gitignored):
+
+```yaml
+odoo:
+  login: gwo-api
+  api_key: "..."
+```
+
+What the API user needs in Odoo: Website > Restricted Editor is enough for `website.page` and `blog.post` SEO fields. Structured data on pages edits the page's view (`ir.ui.view.arch`), which needs Website > Editor and Designer. Do not give it Settings or Administration rights; the adapter never needs them.
+
+Addressable content: `website.page` (matched by exact `url`), `blog.post` (matched by the trailing `-<id>` in the slug) and, when the eCommerce app is installed, `product.template` (`/shop/<slug>-<id>`; category listings are not addressed). Fields: `website_meta_title`, `website_meta_description`, `website_meta_keywords`, `website_meta_og_img`, plus `is_published` and `website_indexed` read-only. Product pages can be added the same way when a client needs them.
+
+Structured data: the adapter manages exactly one element per page, `<script type="application/ld+json" data-gwo="schema">`. On a `website.page` it goes into the view arch before `<div id="wrap">`, outside the structure the website builder owns, so a client editing the page in the builder does not lose it. On a `blog.post` it is appended to `content`; on a `product.template` to `website_description`, which the shop page renders. Reading returns only the managed element; anything the theme emits on its own is left alone and reported separately by `site_page_schema`. Values are serialised with JSON escapes for `&`, `<` and `>` so the arch stays valid XML. Multi-website databases: the page's own view is edited, the generic view is never touched.
+
+## Repository (`write.adapter: repo`)
+
+For sites AI Guru develops. Convention: the repository keeps its SEO metadata in `gwo.seo.json` at the root, keyed by path, and the build reads it.
+
+```json
+{
+  "/he": { "name": "Home", "title": "...", "description": "...", "ogImage": "/og.png",
+           "schema": [{ "@context": "https://schema.org", "@type": "Organization", "name": "...", "url": "https://..." }] },
+  "/he/services": { "name": "Services", "title": "...", "description": null }
+}
+```
+
+Next.js example, in a route's `generateMetadata` and layout:
+
+```ts
+import seo from '../../gwo.seo.json';
+export function generateMetadata({ params }) {
+  const e = seo[`/${params.locale}/${params.slug}`];
+  return { title: e?.title, description: e?.description, openGraph: { images: e?.ogImage ? [e.ogImage] : [] } };
+}
+// in the page component
+{(e?.schema ?? []).map((block, i) => (
+  <script key={i} type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(block).replace(/</g, '\\u003c') }} />
+))}
+```
+
+`schema` is the array of JSON-LD blocks the page emits, in order. `content_set_schema` replaces the whole array; an empty list removes the key.
+
+Site file:
+
+```yaml
+write:
+  adapter: repo
+  repo:
+    url: https://github.com/ai-gur/site
+    branch: main
+    local_path: E:/AI-Guru/sites/site      # a local checkout on the operator machine
+```
+
+The adapter changes the working tree only. Committing and opening a pull request is the GitHub connector's job (phase 6). Until a site adopts the manifest, `ping` fails with a message saying so, and changes for that site are proposals for a developer.
+
+## None (`write.adapter: none`)
+
+Advisory only. Every content change is a proposal. The site is still scanned and reported on.
+
+## Onboarding check
+
+`npm run cli -- site ping <site>` must succeed before a site is declared `full` tier. It authenticates and reports what it can address, without changing anything.

package/docs/adr/ADR-001-shared-mcp-core.md

@@ -0,0 +1,27 @@
+# ADR-001: Shared MCP core with host adapters
+
+**Status:** Accepted
+**Date:** 2026-09-18
+
+## Context
+
+Google Web Operations must be usable from both Claude Code and Codex. Both support MCP. Their packaging and instruction mechanisms differ.
+
+## Decision
+
+One MCP server and one operations core. Claude Code and Codex are hosts, not implementations.
+
+Host-specific material is limited to packaging, configuration, skills, commands and instructions under `hosts/`, and even that is generated (ADR-003).
+
+No business logic, connector logic, policy logic or site-specific logic may exist in a host directory.
+
+## Repository rule
+
+- One repository.
+- One long-lived branch: `main`.
+- Host-specific directories, never host-specific branches.
+- Releases are semantic version tags.
+
+## Consequences
+
+No Claude/Codex behaviour drift. One test surface. One security model. New hosts are a generator target, not a rewrite. Host-native features stay thin.

package/docs/adr/ADR-002-policy-gated-writes.md

@@ -0,0 +1,18 @@
+# ADR-002: Policy-gated, verified writes
+
+**Status:** Accepted
+**Date:** 2026-09-18 (enforcement added in v0.2)
+
+## Decision
+
+Every mutating operation has one of three risk classes: `auto`, `approval_required`, `protected`. The class is resolved from `policies/default.yaml` plus site overrides before execution.
+
+Classification alone is not enough. `packages/policy` exposes `enforce()`, which throws unless the action may proceed. Every write path calls it. `approval_required` passes only with the token `<site_id>:<action>` supplied in the current session. `protected` never passes.
+
+Site overrides may raise a class and may not lower one. Host prompts cannot change a class at all.
+
+Every write records the state before, the state after, and the result of a verification read. A write whose verification failed is a failed write, whatever the API returned.
+
+## Consequences
+
+An agent can be trusted with write tools because the tools refuse what policy forbids. Approval is explicit and auditable. Rollback is possible because the previous value is always recorded.

package/docs/adr/ADR-003-single-source-playbooks.md

@@ -0,0 +1,18 @@
+# ADR-003: Playbooks are the single source; hosts are generated
+
+**Status:** Accepted
+**Date:** 2026-09-18
+
+## Context
+
+Operating knowledge (what a daily run checks, when to escalate, what may be fixed autonomously) is the most valuable and most drift-prone part of the system. Claude Code consumes it as skills with frontmatter; Codex consumes it as one instructions file. Two hand-maintained copies diverge within weeks.
+
+## Decision
+
+Playbooks live once, in `packages/playbooks/*.md`, with frontmatter (`name`, `description`). `tools/build-hosts.ts` generates `hosts/claude` (plugin manifest, `.mcp.json`, one skill per playbook, slash commands) and `hosts/codex` (plugin manifest, the same skills, `AGENTS.md`, a config template). Both hosts consume the SKILL.md format unchanged; the only per-host differences are the manifest, Claude's slash commands, and how the MCP server is registered.
+
+`hosts/` is committed so the plugin installs from a checkout without a build step, but it is never edited by hand. CI regenerates it and fails on any difference.
+
+## Consequences
+
+One edit updates both hosts. Adding a host is a generator branch, not new content. Reviewers read playbooks, not generated files.

package/docs/adr/ADR-004-native-typescript-runtime.md

@@ -0,0 +1,16 @@
+# ADR-004: TypeScript executed natively, no build step
+
+**Status:** Accepted
+**Date:** 2026-09-18
+
+## Context
+
+The code should be typed, because two different agents will edit it. But a build step means a `dist/` to keep in sync, and a runtime transpiler such as `tsx` means a dev dependency on the production path. Both hosts launch the MCP server directly, so the launch command must work on a clean checkout.
+
+## Decision
+
+Source is TypeScript restricted to erasable syntax (`erasableSyntaxOnly`), with explicit `.ts` import extensions and `verbatimModuleSyntax`. Node 22.18+ strips types natively, so `node apps/mcp-server/src/index.ts` runs as-is. `tsc --noEmit` checks types in `npm run check` and CI. There is no `dist/` and no transpiler at runtime.
+
+## Consequences
+
+Zero build. The generated `.mcp.json` and `config.toml` invoke `node` on the source file. Enums, namespaces and parameter properties are unavailable; interfaces, type aliases and unions cover everything this codebase needs. Contributors must import with `.ts` extensions and use `import type` for types.

package/docs/adr/ADR-005-two-token-publish.md

@@ -0,0 +1,22 @@
+# ADR-005: Publishing a container needs a review token as well as approval
+
+**Status:** Accepted
+**Date:** 2026-09-18 (v0.4)
+
+## Context
+
+A Tag Manager publish is the widest-reaching write the system makes: one version can silently stop every conversion on a site, or start sending visitor data somewhere new. The approval token from ADR-002 proves the operator agreed to *a* publish for *a* site. It does not prove they saw what would ship, and a workspace can change between the moment they looked and the moment the publish runs, whether by another staged write, by a client editing in the UI, or by someone else publishing a version underneath it.
+
+## Decision
+
+Every Tag Manager change is staged into a workspace whose name carries the policy prefix (`gwo-`). `gtm_workspace_diff` computes the workspace's changes against the live version and derives a **review token**: a short hash of the exact set of changed entities (kind, id, name, change status, entity fingerprint) and the live version id.
+
+`gtm_publish` requires both the approval token for `gtm.publish` and a review token. Inside the write, before creating a version, the current diff is recomputed and its token compared; a mismatch fails the write and records why. The workspace is synced first, and the token is checked again after the sync, so a version published by someone else in between also invalidates it.
+
+The two gates are enforced in `packages/core/src/gtm-ops.ts`, not by prompt. A host cannot skip either.
+
+## Consequences
+
+Nothing publishes that was not diffed, and nothing publishes a diff that moved after it was reviewed. The cost is one extra read per publish and a second value the operator passes back. Stage results carry the token so the common path (stage, look, publish) needs no separate diff call.
+
+The same shape applies to any future write whose effect is a set of changes rather than one value: compute a token from the set, require it back.

package/docs/adr/ADR-006-one-package-one-installer.md

@@ -0,0 +1,20 @@
+# ADR-006: One npm package, one installer, state outside the package
+
+**Status:** Accepted
+**Date:** 2026-09-18 (v0.5)
+
+## Context
+
+Until v0.4 the system ran from a repository checkout: sites, data and secrets sat next to the code, Claude Code loaded the plugin from `hosts/claude`, and Codex needed a separate installer. Distributing that to a second machine or a colleague meant cloning the repository and following two sets of steps.
+
+## Decision
+
+The repository is an npm package (`google-web-operations`) with one executable, `gwo`. `npm i -g` from a release tarball or from GitHub installs the code; `gwo install` registers the MCP server, skills and slash commands with both hosts in one run, from the same generated `hosts/` tree, and seeds the operator state directory.
+
+Operator state (sites, data, secrets, `.env`, an optional tightened policy) lives in `GWO_HOME`, default `~/.gwo`. A repository checkout is detected by its `.git` and keeps state next to the code, so development is unchanged. Upgrading the package never touches state.
+
+The hosts launch the server as `node <package>/apps/mcp-server/src/index.ts` with absolute paths written at install time, because neither host expands variables in a user-scope MCP entry. `gwo install` is idempotent and rewrites those paths after an upgrade.
+
+## Consequences
+
+One command installs everything on a new machine; the same command repairs it after an upgrade. Development keeps ADR-004 (TypeScript run natively, no build step), but the package itself ships JavaScript: Node refuses to strip types for files under `node_modules`, so `tools/build-package.ts` compiles to `build/` with `.ts` imports rewritten to `.js`, copies the non-code parts (policies, hosts, playbooks, site templates, docs, scheduler) to the same relative paths, and `npm pack` runs there. The bin, the installer and the scheduler pick `.js` when it exists and `.ts` otherwise, so the same files serve both layouts. Releases are tags; CI packs the tarball and attaches it to the GitHub release. The Claude Code plugin directory stays generated for people who prefer `claude plugin` flows, but the installer does not depend on it.

package/hosts/claude/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "google-web-operations",
+  "version": "0.6.4",
+  "description": "Google Web Operations: agent-run SEO and GEO operations for client websites. One core, one MCP server, two hosts (Claude Code, Codex).",
+  "author": {
+    "name": "AI Guru"
+  },
+  "mcpServers": "./.mcp.json"
+}

package/hosts/claude/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "google-web-operations": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/../../apps/mcp-server/src/index.ts"
+      ]
+    }
+  }
+}

package/hosts/claude/README.md

@@ -0,0 +1,7 @@
+<!-- GENERATED by tools/build-hosts.ts from packages/playbooks. Do not edit here. -->
+
+# Google Web Operations for Claude Code
+
+Install with `gwo install claude` (user-scope MCP server, skills and commands), or load this directory as a plugin.
+
+Commands: /gwo-daily, /gwo-weekly, /gwo-monthly, /gwo-triage, /gwo-onboard, /gwo-scan, /gwo-setup, /gwo-add-site, /gwo-measure.

package/hosts/claude/commands/gwo-add-site.md

@@ -0,0 +1,7 @@
+---
+description: Register the site in $ARGUMENTS.
+---
+
+<!-- GENERATED by tools/build-hosts.ts from packages/playbooks. Do not edit here. -->
+
+Register the site in $ARGUMENTS. Load gwo-setup and gwo-onboarding; ask only for what cannot be inferred, then ops_add_site, baseline scan, and the access checklist for the client.

package/hosts/claude/commands/gwo-daily.md

@@ -0,0 +1,7 @@
+---
+description: Run the daily health pass.
+---
+
+<!-- GENERATED by tools/build-hosts.ts from packages/playbooks. Do not edit here. -->
+
+Run the daily health pass. Load skills gwo-operating-model and gwo-daily, then execute for every enabled site, or only the site named in $ARGUMENTS.

package/hosts/claude/commands/gwo-measure.md

@@ -0,0 +1,7 @@
+---
+description: Audit measurement for the site in $ARGUMENTS.
+---
+
+<!-- GENERATED by tools/build-hosts.ts from packages/playbooks. Do not edit here. -->
+
+Audit measurement for the site in $ARGUMENTS. Load gwo-operating-model and gwo-measurement, run the audit, and propose staged Tag Manager changes with their tokens.

package/hosts/claude/commands/gwo-monthly.md

@@ -0,0 +1,7 @@
+---
+description: Run the monthly deep scan and produce both reports.
+---
+
+<!-- GENERATED by tools/build-hosts.ts from packages/playbooks. Do not edit here. -->
+
+Run the monthly deep scan and produce both reports. Load gwo-operating-model, gwo-monthly and gwo-client-report-template. Site: $ARGUMENTS or all.

package/hosts/claude/commands/gwo-onboard.md

@@ -0,0 +1,7 @@
+---
+description: Onboard the site in $ARGUMENTS.
+---
+
+<!-- GENERATED by tools/build-hosts.ts from packages/playbooks. Do not edit here. -->
+
+Onboard the site in $ARGUMENTS. Load gwo-operating-model and gwo-onboarding.

package/hosts/claude/commands/gwo-scan.md

@@ -0,0 +1,7 @@
+---
+description: Run web_scan_site for the site in $ARGUMENTS and summarise the findings in the operator tone from gwo-operating-model.
+---
+
+<!-- GENERATED by tools/build-hosts.ts from packages/playbooks. Do not edit here. -->
+
+Run web_scan_site for the site in $ARGUMENTS and summarise the findings in the operator tone from gwo-operating-model.

package/hosts/claude/commands/gwo-setup.md

@@ -0,0 +1,7 @@
+---
+description: Set up or administer the system from the chat.
+---
+
+<!-- GENERATED by tools/build-hosts.ts from packages/playbooks. Do not edit here. -->
+
+Set up or administer the system from the chat. Load gwo-setup, call ops_setup_status, and walk the operator through the next step: $ARGUMENTS.

package/hosts/claude/commands/gwo-triage.md

@@ -0,0 +1,7 @@
+---
+description: Triage an incident for the site in $ARGUMENTS.
+---
+
+<!-- GENERATED by tools/build-hosts.ts from packages/playbooks. Do not edit here. -->
+
+Triage an incident for the site in $ARGUMENTS. Load gwo-operating-model and gwo-triage. Find the cause before proposing any fix.

package/hosts/claude/commands/gwo-weekly.md

@@ -0,0 +1,7 @@
+---
+description: Run the weekly improvement pass.
+---
+
+<!-- GENERATED by tools/build-hosts.ts from packages/playbooks. Do not edit here. -->
+
+Run the weekly improvement pass. Load gwo-operating-model and gwo-weekly, then execute for every enabled site, or only $ARGUMENTS.

package/hosts/claude/skills/gwo-client-report-template/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: gwo-client-report-template
+description: Structure and tone for the client-facing monthly report. Plain language, three questions, one small table.
+---
+
+<!-- GENERATED by tools/build-hosts.ts from packages/playbooks. Do not edit here. -->
+
+# Client report template
+
+Write in the client's language (Hebrew for Israeli clients unless the site file says otherwise). One page. The document is produced by `report_client_monthly`; the four fields you pass map to the four sections below, and whatever you leave out is derived from the month's data.
+
+## How the site is doing
+
+Two or three sentences. More or fewer visitors from search than last month, and is that expected. One number that matters: clicks from Google this month vs last month.
+
+| | This month | Last month | Change |
+|---|---|---|---|
+| Visits from Google | | | |
+| Times shown in results | | | |
+| Average position | | | |
+
+## What we did this month
+
+A short list, in business terms. Not "fixed canonical.cross-host on 12 pages" but "fixed a setup issue that was splitting the site's ranking signal between two addresses".
+
+## What we need from you
+
+Only things that require the client: approvals for proposed changes, content they need to write, decisions on direction. If nothing, say "nothing this month".
+
+## Next month
+
+One or two sentences on the focus.
+
+---
+
+Never include: rule ids, tool names, severity labels, raw query lists, or anything the client cannot act on.

package/hosts/claude/skills/gwo-content-brief/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: gwo-content-brief
+description: How to write titles, meta descriptions and structured-data proposals for client sites, in Hebrew and English, so that search engines and answer engines both pick them up. Load before any content write.
+---
+
+<!-- GENERATED by tools/build-hosts.ts from packages/playbooks. Do not edit here. -->
+
+# Content brief
+
+You write the text. The tools validate and apply it. Follow this brief exactly; the validator enforces the measurable parts and the operator reviews the rest.
+
+## Meta description
+
+**Length by script.** Hebrew renders denser than Latin text, so the same snippet width holds fewer characters.
+
+| Script | Characters |
+|---|---|
+| Hebrew | 120 to 150 |
+| Latin (English) | 70 to 160 |
+
+**Structure.** Answer first, then the reason to click. The first clause states what the page delivers. The last clause invites the action or names who it is for. One idea per sentence. No line breaks, no HTML, no quotation marks around the whole text.
+
+**Terms.** The page's primary term appears once, early. Never repeat a term more than twice; repetition lowers visibility with answer engines and reads as spam to people.
+
+**Hebrew rules.**
+- Ktiv maleh throughout: תוכנה, שירות, אינטרנט.
+- Gender-neutral phrasing: "ניתן", "אפשר", "יש ל" instead of "אתה יכול", "המשתמש צריך".
+- Business register, direct. No English-style softeners ("נשמח אם", "ייתכן שכדאי"). Say the thing.
+- Established tech terms stay in English or in their spoken transliteration: API, SaaS, אימייל, סטארטאפ. Brand names stay as written.
+- No calques: "בשורה התחתונה" not "בסוף היום"; "כדי" not "בכדי".
+- Digits for numbers in body copy: "תוך 24 שעות".
+
+**English rules.** Sentence case. Primary term in the first 60 characters. No exclamation marks. Numbers as digits.
+
+**Do not** write a description that could belong to any page. If it does not name what this page uniquely offers, rewrite it.
+
+## Title
+
+50 to 60 characters, primary term near the beginning, brand at the end after one separator (`|`). Hebrew titles count Hebrew characters the same way. The validator in `content_set_title` rejects under 15 or over 65 characters, more than one separator, a repeated term, HTML and line breaks. Do not change a title on a page that already ranks without a Search Console reason; it is the most expensive edit in this playbook, and it always needs the token for `content.title.update`.
+
+## Structured data
+
+Answer engines cite sources; they do not rank pages. Schema tells them what a page is.
+
+- Sitewide: `Organization` (or `Person` for a personal brand) with name, url, logo, sameAs.
+- Per template: `WebPage`, `Article` (with author and dates), `Service`, `Product`, `LocalBusiness` where true.
+- `FAQPage` wherever the page already answers concrete questions. Each answer 2 to 3 sentences, answer first, a number or a source where one exists. Never invent questions the page does not answer.
+- Check `site_page_schema` first: the theme may already emit `WebSite` or `Organization`. Never add a type the page already has; two `Organization` blocks with different names is worse than none.
+- Write the exact JSON-LD blocks and apply them with `content_set_schema`. The validator requires `"@context": "https://schema.org"` and an `@type` on every block, a non-empty `mainEntity` on `FAQPage`, no `</script` inside values, and at most 20 KB per page. Structured data is approval-required on every site: propose the blocks and the token for `content.schema.update` together.
+- On Odoo the blocks go into the page's view; on repository sites into the manifest entry's `schema` array, which the layout renders. Either way the live page shows them only after the next render or deploy: verify with `web_inspect_url` and say "stored, awaiting deploy" until it does.
+
+## Content that gets cited
+
+When proposing page-level content changes (weekly and monthly runs), prefer, in this order: a specific statistic with its source; a short expert quote with attribution; a direct answer in the first paragraph; headed sections an engine can lift; a comparison table. Avoid keyword stuffing, which measurably hurts. Fluency plus statistics is the strongest combination.
+
+## Before you submit any text
+
+1. Run it through `content validate` (CLI) or rely on the tool's validation.
+2. Read it aloud once in the page's language. If it sounds translated, it is.
+3. Check the page still has exactly one H1 and that the description does not contradict it.