@aiguru/google-web-operations 0.6.4

package/docs/GETTING-STARTED.he.md

@@ -0,0 +1,63 @@
+# Google Web Operations: התחלה מהירה
+
+מערכת תפעול שוטף לאתרי לקוחות בגוגל ובמנועי תשובה מבוססי AI. היא סורקת, קוראת Search Console, Analytics ו‑Tag Manager, מתקנת מה שמותר לה לתקן, מאמתת כל שינוי, ורושמת הכול. עובדים איתה מתוך Claude Code או Codex, בשיחה.
+
+## התקנה (פעם אחת בכל מחשב)
+
+דרישות: Node 22.18 ומעלה.
+
+1. בטרמינל:
+   ```
+   npm i -g @aiguru/google-web-operations
+   gwo install
+   ```
+2. הפעלה מחדש של Claude Code או Codex.
+
+`gwo install` רושם את שרת ה‑MCP, את הסקילים ואת הפקודות בשני ההוסטים, ויוצר את תיקיית המצב `~/.gwo` (אתרים, נתונים, סודות, הגדרות). שדרוג בעתיד: `gwo update`.
+
+לבדיקה שהכול במקום: `gwo doctor`.
+
+## השיחה הראשונה
+
+ב‑Claude Code: `/gwo-setup`. ב‑Codex: "הגדר את Google Web Operations". הסוכן קורא את מצב ההגדרה ומוביל צעד אחר צעד:
+
+1. **חיבור לגוגל.** פרויקט Google Cloud אחד לכל הלקוחות, לקוח OAuth מסוג Desktop app, הורדת ה‑JSON. הסוכן מבקש את הנתיב לקובץ, לא את התוכן. ואז דפדפן נפתח להסכמה עם חשבון התפעול של החברה.
+2. **אתר ראשון.** כתובת, שם, פלטפורמה (Odoo, Next.js, WordPress, אחר). השאר ברירות מחדל. הסוכן מבצע סריקת בסיס ומנסח ללקוח את רשימת ההרשאות שהוא צריך לתת לחשבון התפעול: Search Console, GA4, ובמידת הצורך Tag Manager.
+3. **אחרי שהלקוח נתן הרשאות.** "גלה את הנכסים" ממלא את המזהים בקובץ האתר.
+
+## עבודה שוטפת
+
+| פקודה | מה קורה |
+|---|---|
+| `/gwo-daily` | בדיקת בריאות שקטה. מדווח רק על שינויים ותקלות |
+| `/gwo-weekly` | סבב שיפורים: ממצאים פתוחים, הזדמנויות מ‑Search Console, תיקונים במסגרת המדיניות |
+| `/gwo-monthly` | סריקה עמוקה ודוח לקוח כקובץ Word |
+| `/gwo-triage <site>` | חקירת תקלה: ירידה בתנועה, אובדן אינדוקס, מדידה שנשברה |
+| `/gwo-measure <site>` | אודיט מדידה ושינויים ב‑Tag Manager דרך סביבת עבודה מבוקרת |
+| `/gwo-scan <site>` | סריקה אחת עכשיו |
+| `/gwo-add-site <url>` | רישום אתר חדש |
+
+ב‑Codex אין פקודות slash, אבל אותם סקילים נטענים לפי הכוונה: "תריץ את הבדיקה היומית", "מה קרה לתנועה של דורית", "דוח חודשי לאתר X".
+
+## שלוש רמות סיכון, ולא יותר
+
+- **auto**: הסוכן מבצע ומדווח. סריקות, קריאות, הגשת sitemap, מילוי תיאור ריק.
+- **approval_required**: הסוכן מציע ומציג טוקן בצורה `<site>:<action>`. מדביקים את הטוקן בחזרה, והוא מבצע. כותרות, נתונים מובנים, אירועי מפתח, שינויי Tag Manager.
+- **protected**: לעולם לא. מחיקות, חיוב, הרשאות משתמשים.
+
+פרסום ב‑Tag Manager דורש גם review token שמחושב מהדיף שהוצג. אם משהו זז מאז, הפרסום נדחה.
+
+## החלטות אתר
+
+כשלקוח אומר "זה בכוונה" (למשל GA4 בלי Tag Manager), אומרים לסוכן והוא רושם דיכוי עם הסיבה. הממצא נספר בכותרת של כל דוח אבל מפסיק להיות רעש.
+
+## איפה הדברים
+
+- `~/.gwo/sites/` קובץ YAML לכל אתר. סודות ב‑`<host>.secrets.yaml`, ידנית בלבד.
+- `~/.gwo/.gwo-data/<site>/` סריקות, snapshots, יומן ביקורת, דוחות.
+- `~/.gwo/.env` הגדרות: תבנית Word לדוחות, Resend למשלוח, GitHub ל‑pull requests.
+- `~/.gwo/secrets/` לקוח OAuth וטוקן מוצפן.
+
+## עזרה
+
+`gwo` בלי פרמטרים מציג את כל הפקודות. `gwo doctor` אומר מה חסר ומה הצעד הבא.

package/docs/HOSTED-WORKER.md

@@ -0,0 +1,36 @@
+# Hosted worker
+
+The daily and weekly runs should not depend on one laptop being on at 07:00. Any always-on Linux host works: a small VM, a NAS, a container platform. The worker needs no agent, no browser and no inbound ports.
+
+## What runs
+
+`gwo worker loop` (the container's default command) runs `gwo worker daily` every day at `GWO_DAILY_AT` and `gwo worker weekly` on `GWO_WEEKLY_DAY` at `GWO_WEEKLY_AT`, in `TZ`. With `RESEND_API_KEY` set, reports are emailed; otherwise they stay under `.gwo-data/_runs/` in the state volume. Each run is a child process with its exit code logged (0 healthy, 2 escalations, 1 failures).
+
+## Build and run
+
+```
+docker compose -f deploy/compose.yml up -d
+docker logs -f gwo-worker
+```
+
+The image compiles the package (`npm run build:package`) and installs runtime dependencies only. State lives in the `gwo-home` volume at `/home/gwo/.gwo`, the same layout as `~/.gwo` on a workstation: `sites/`, `.gwo-data/`, `secrets/`, `.env`.
+
+## Hand over configuration
+
+1. **Sites.** Copy `sites/*.yaml` (and any `*.secrets.yaml`) into the volume: `docker cp sites/. gwo-worker:/home/gwo/.gwo/sites/`.
+2. **Environment.** Put `RESEND_API_KEY`, `GWO_REPORT_FROM`, `GWO_REPORT_TO` in `/home/gwo/.gwo/.env` inside the volume (or as container environment).
+3. **Google token.** A headless host cannot complete the browser consent, so authorise on a workstation with the portable store and copy the result:
+
+   ```
+   GWO_TOKEN_STORE=aes gwo auth login        # on the workstation; writes secrets/google-token.enc and secrets/.token-key
+   docker cp secrets/google-token.enc gwo-worker:/home/gwo/.gwo/secrets/
+   docker cp secrets/.token-key       gwo-worker:/home/gwo/.gwo/secrets/
+   docker cp secrets/oauth-client.json gwo-worker:/home/gwo/.gwo/secrets/
+   ```
+
+   The key file is what protects the token; keep the pair together and nowhere else. On Windows the default store is DPAPI, which cannot be moved; that is why the login above forces AES.
+4. **Check.** `docker exec gwo-worker node /opt/gwo/bin/gwo.js setup` prints the same status the chat tool shows; `docker exec gwo-worker node /opt/gwo/bin/gwo.js worker daily` runs once immediately.
+
+## What the hosted worker does not do
+
+It senses and escalates. Writes, triage and reports stay with the agent on a workstation, which reads the same state when it is a checkout or the same `~/.gwo` when installed. Two machines can share state only if the volume is shared; otherwise the workstation's scans and the host's scans are separate histories, which is fine for a sensing-only host.

package/docs/INSTALL.he.md

@@ -0,0 +1,57 @@
+# התקנה: Google Web Operations
+
+## דרישות
+
+- Node 22.18 ומעלה (`node --version`)
+- Claude Code ו/או Codex מותקנים
+
+## 1. התקנה
+
+```
+npm i -g @aiguru/google-web-operations
+gwo install
+```
+
+`gwo install` רושם את שרת ה‑MCP, את הסקילים ואת הפקודות בקלוד ובקודקס, ויוצר את `~/.gwo`. רק להוסט אחד: `gwo install claude` או `gwo install codex`. לראות בלי לשנות: `gwo install --print`.
+
+חלופה בלי npm: להוריד את ה‑tgz מעמוד ה‑Releases בריפו ולהריץ `npm i -g ./aiguru-google-web-operations-<version>.tgz` (ה‑`./` חובה).
+
+## 2. הפעלה מחדש ובדיקה
+
+הפעלה מחדש של Claude Code ו‑Codex, ואז:
+
+```
+gwo doctor
+```
+
+הפלט אומר מה מוגדר, מה חסר, ומה הצעד הבא.
+
+## 3. השיחה הראשונה
+
+- Claude Code: `/gwo-setup`
+- Codex: "הגדר את Google Web Operations"
+
+הסוכן מוביל: חיבור לגוגל (לתת לו את הנתיב לקובץ ה‑JSON של לקוח ה‑OAuth, לא את התוכן), הסכמה בדפדפן עם חשבון התפעול, רישום אתר ראשון, ורשימת ההרשאות שהלקוח צריך לתת.
+
+מחשב שני שאמור לראות את אותם אתרים: להעתיק את `sites/*.yaml` ל‑`~/.gwo/sites/`. ההסכמה לגוגל נעשית מחדש בכל מחשב (הטוקן קשור למשתמש).
+
+## שדרוג
+
+```
+gwo update
+```
+
+## הסרה
+
+```
+gwo uninstall
+```
+
+מסיר את הרישומים בהוסטים בלבד. `~/.gwo` נשארת.
+
+## אופציונלי
+
+- בדיקת DOM מרונדר (`web_inspect_rendered`): `npm i -g playwright && npx playwright install chromium`
+- דוח לקוח בתבנית החברה: `GWO_DOCX_TEMPLATE` ב‑`~/.gwo/.env`
+- משלוח דוחות במייל: `RESEND_API_KEY`, `GWO_REPORT_FROM`, `GWO_REPORT_TO`
+- Pull requests לאתרי רפו: `GITHUB_TOKEN`

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

@@ -0,0 +1,153 @@
+# Google Web Operations: Product and Technical Specification v0.2
+
+Supersedes v0.1 (2026-09-18). v0.2 merges two independent v0.1 designs into one codebase: the skeleton, tooling and Google connectors from one, the crawl engine, rule set, snapshots, playbooks and policy enforcement from the other.
+
+## 1. Purpose
+
+Google Web Operations is an operational control layer for a portfolio of client websites. It continuously observes technical health, search visibility, AI answer-engine readiness and measurement instrumentation; turns observations into findings; and, within policy, prepares or executes remediation and verifies it.
+
+It runs identically from Claude Code and Codex through one MCP server, and without any agent through a scheduled worker.
+
+## 2. Principles
+
+1. **One source of truth.** One repository, one long-lived branch, one operations core, one set of playbooks. Hosts are generated.
+2. **Host-neutral.** Claude Code and Codex differences are packaging and instructions only.
+3. **Observe before changing.** Every write is preceded by a read of current state.
+4. **Policy before action.** Risk class is data, resolved before execution, and enforced in code. A prompt cannot lower it.
+5. **Verify every write.** A write is complete when a fresh read shows the change. Not before.
+6. **Auditability.** Every run and every write has a durable record with before, after and verification.
+7. **No secret sprawl.** Site records carry references. Credentials live in gitignored secrets files and, in phase 2, an encrypted token store.
+8. **Background-capable.** Sensing runs on a schedule without an interactive session. Deciding and acting need an agent.
+9. **Bounded output.** Tools return summaries sized for a model's context. Full data stays on disk.
+
+## 3. Scope of v0.2
+
+### Delivered and verified
+
+- Site registry (YAML, defaults, secrets merge, lookup by id or host).
+- Policy engine: three risk classes, exact and prefix matching, site overrides that only tighten, token-gated enforcement.
+- Storage: per-site scans, snapshots, snapshot diff, audit log.
+- Web crawler: redirect chains, robots.txt with per-agent evaluation for 2 search and 14 AI crawlers, llms.txt, host-variant probe, sitemap and sitemap index, bounded-concurrency page fetch.
+- Rule engine: 25 page rules and 17 site rules across indexability, metadata, structure, i18n, structured data, GEO, measurement, sitemap and performance.
+- Google connectors with a swappable token provider: Search Console (performance summary with striking-distance list, raw query, sitemaps, URL inspection, sitemap submit), GA4 Data and Admin (traffic summary, raw report, realtime, key events, data streams), PageSpeed (summary with lab and field CWV).
+- MCP server: 17 tools, underscore names, bounded outputs.
+- Worker: daily/weekly/monthly sensing for all sites, audit-logged, non-zero exit on failure.
+- CLI: sites, scan, inspect, diff, classify, audit.
+- Seven playbooks, generated into Claude skills and commands and into Codex AGENTS.md.
+- Tests for policy, registry, parser and rules. CI on push.
+
+### v0.3 in progress
+
+- **Durable Google OAuth: implemented, awaiting first consent.** Authorisation-code flow with PKCE and loopback redirect; refresh token encrypted at rest (DPAPI on Windows, AES-256-GCM elsewhere); silent refresh with in-memory cache; least-privilege default scopes with deliberate escalation per write capability; provider auto-selection (stored OAuth, else env bridge). CLI `auth login|status|logout`. Property discovery matches Search Console, GA4 and Tag Manager inventory to sites by host and applies ids to site YAML with `discover --apply`, preserving comments. MCP tools `google_auth_status` and `google_discover_properties`. Unit-tested: PKCE, both stores, refresh and cache, matching. The consent run itself needs `secrets/oauth-client.json` from the operator.
+
+- **Live Google reads: verified** on both pilot sites through the stored authorisation with silent refresh: Search Console performance, sitemaps and URL inspection; GA4 data streams, traffic by channel, daily report, realtime and key events; PageSpeed mobile and desktop (attributed to the project via the OAuth token, since the keyless shared quota is unreliable).
+- **The write loop: implemented and used.** `performWrite()` in core enforces policy, reads before, executes, reads after, verifies, and records before/after/verified. Blocked attempts are recorded too. First write built on it: `gsc_submit_sitemap` (policy `auto`), verified by `lastSubmitted` advancing in Search Console.
+
+- **Tag Manager read: implemented.** Accounts, containers, workspaces, version headers, live version. Snapshots are shaped into a compact record (tags with resolved trigger names, paused state), persisted per site, and diffed to surface versions, tags, triggers and variables that changed. Tools `gtm_containers`, `gtm_versions`, `gtm_snapshot`, `gtm_diff`.
+
+- **Site write adapters: implemented.** One interface (`ping`, `listPages`, `readPageSeo`, `writePageSeo`). Odoo over JSON-RPC with a dedicated API user and key, addressing `website.page` and `blog.post` SEO fields. Repository adapter over a `gwo.seo.json` manifest convention for sites AI Guru develops. Read tools `site_adapter_ping`, `site_pages`, `site_page_seo`; writes arrive in phase 5 through `performWrite()`. Tested against a fake JSON-RPC server and a temp checkout; no live Odoo client yet. See `docs/SITE-ADAPTERS.md`.
+
+- **First content and configuration writes: implemented.** `content_set_meta_description` validates text by script (Hebrew 120 to 150 characters, Latin 70 to 160; no stuffing, HTML, breaks or caps), chooses the policy class from the stored value (empty field is `auto`, replacement is `approval_required`), applies through the site adapter inside the write loop and verifies by re-reading. `ga4_create_key_event` (approval required, idempotent) marks an event as a key event and verifies by listing. A content brief playbook (`gwo-content-brief`) encodes Hebrew SEO rules and answer-engine citation practices for the text the agent writes. Scan rules for description length are now script-aware.
+
+### Deferred
+
+- Tag Manager staged write and publish.
+- Structured-data injection for Odoo pages (QWeb view edits).
+- Title updates and JSON-LD writes through the adapters (the brief covers them; the tools follow the same loop).
+- The first Google write, `ga4.key_event.create`.
+- Cloudflare (cache purge, rules) and Resend (report delivery) connectors.
+- Scheduled deployment and alerting.
+- Client report rendering to a document.
+
+## 4. Architecture
+
+```
+Claude Code ──┐
+              ├── apps/mcp-server ──┐
+Codex ────────┘                     ├── packages/core ── connectors/web-crawler
+                                    │        │           connectors/google
+apps/worker (cron) ─────────────────┤        ├── packages/policy
+                                    │        └── packages/storage
+apps/cli ───────────────────────────┘
+packages/playbooks ── tools/build-hosts ──> hosts/claude, hosts/codex
+```
+
+- `packages/core` owns the operations engine, registry, rule engine and types. It knows nothing about hosts.
+- Connectors are pure I/O. No rules live in a connector.
+- `packages/policy` is the only place execution can be refused.
+- `packages/storage` is the only place state is written.
+- `hosts/` is generated output. CI fails on a hand edit.
+
+TypeScript runs natively on Node 22.18+ (type stripping). There is no build step and no runtime transpiler. Types are checked by `tsc --noEmit` in CI.
+
+## 5. Operational loop
+
+```
+Observe -> Classify -> Authorise -> Execute -> Verify -> Record
+```
+
+On verification failure: rollback where the target supports it, escalate, record the failure.
+
+## 6. Risk classes and enforcement
+
+| Class | Meaning | Gate |
+|---|---|---|
+| `auto` | Read, analyse, report, or reversible with tiny blast radius | none |
+| `approval_required` | Any content, schema, canonical, redirect, tag or configuration change | token `<site_id>:<action>` supplied in-session |
+| `protected` | Deletion, account-level, retention, access, billing, legal, privacy | never |
+
+`policies/default.yaml` is the source of truth. `packages/policy` resolves exact match over prefix match, most restrictive prefix wins, and site overrides may only raise a class. `enforce()` throws `PolicyError`; every write path must call it.
+
+## 7. Schedules
+
+| Cadence | Pages | What it looks for |
+|---|---|---|
+| Daily | 25 | Regressions since yesterday: status, noindex, canonical, tracking id, robots, sitemap size, host split, click drop |
+| Weekly | 200 | Full findings list, striking-distance, decay, cannibalisation, CWV, verification of last week's fixes |
+| Monthly | 200 | Structured data per template, GEO readiness, measurement hygiene, coverage, three-month trend, client report |
+
+The worker performs the sensing half on schedule. An agent performs the deciding and acting half on demand or when triggered by the worker's output.
+
+## 8. Tool surface (MCP)
+
+| Tool | Class | Needs Google |
+|---|---|---|
+| `ops_list_sites`, `ops_get_site`, `ops_classify_action`, `ops_audit_log` | read | no |
+| `web_scan_site`, `web_inspect_url`, `web_diff_scans` | read | no |
+| `google_auth_status` | read | no |
+| `gsc_performance`, `gsc_search_analytics`, `gsc_sitemaps`, `gsc_inspect_url` | read | yes |
+| `ga4_traffic`, `ga4_run_report`, `ga4_realtime`, `ga4_key_events` | read | yes |
+| `pagespeed_check` | read | optional key |
+| `gsc_submit_sitemap` | write, `auto` | yes |
+| `gtm_containers`, `gtm_versions`, `gtm_snapshot`, `gtm_diff` | read | yes |
+| `site_adapter_ping`, `site_pages`, `site_page_seo` | read | no (site credentials) |
+| `content_set_meta_description` | write, `auto` when empty, else `approval_required` | no (site credentials) |
+| `ga4_create_key_event` | write, `approval_required` | yes, `analytics.edit` |
+
+Future write tools are narrow and named for one effect: `ga4_create_key_event`, `content_update_meta_description`, never `google_change_setting`.
+
+## 9. Data model
+
+- `sites/<host>.yaml`: registry record, schema in `sites/schema.yaml`.
+- `.gwo-data/<site_id>/latest-scan.json`: last full scan.
+- `.gwo-data/<site_id>/snapshots/<ts>.json`: fingerprints for diffing.
+- `.gwo-data/<site_id>/audit.jsonl`: one record per run, proposal, write or block. Writes carry `before`, `after`, `verified`.
+
+## 10. Security
+
+See `docs/SECURITY.md`. In short: no credentials in the registry or the repository; stdout of the MCP process is protocol-only; visitor PII never passes through this system; every write is policy-gated, recorded and verified.
+
+## 11. Pilot success criteria
+
+For `doritgrinberg.co.il` and `aiguru.co.il`, v0.2 is operational when:
+
+1. `npm run check` passes locally and in CI.
+2. `web_scan_site` returns findings for both sites from both hosts.
+3. The worker records a daily run for both sites.
+4. With a token configured, `gsc_performance` and `ga4_traffic` return live data.
+
+Items 1 to 3 are met at the time of writing. Item 4 waits on Google access.
+
+## 12. v0.3 target
+
+Durable OAuth and property discovery; Tag Manager read; Odoo and repository write adapters; `ga4_create_key_event` as the first verified write; scheduled worker deployment with alerting.

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

@@ -0,0 +1,86 @@
+# Google Web Operations: Product and Technical Specification v0.3
+
+Supersedes v0.2 (kept for history). v0.3 completes the six-step plan: durable Google access, live reads, Tag Manager read, site write adapters, the first verified writes, and scheduled operation with delivery.
+
+## 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.
+
+## 3. What v0.3 delivers
+
+| Area | Delivered |
+|---|---|
+| Google access | Authorisation-code OAuth with PKCE and loopback; refresh token encrypted at rest (DPAPI on Windows, AES-GCM elsewhere); silent refresh; least-privilege default scopes with explicit escalation per write capability; property discovery that fills site files |
+| Reads | Search Console (performance summary with striking distance, raw query, sitemaps, URL inspection), GA4 (streams, traffic, daily report, realtime, key events), PageSpeed (attributed to the project), Tag Manager (accounts, containers, versions, live-version snapshot and diff) |
+| Site adapters | One interface; Odoo over JSON-RPC with a dedicated API user (`website.page`, `blog.post`); repository manifest `gwo.seo.json` for sites AI Guru develops |
+| Writes | The write loop `performWrite()`: enforce, read before, execute, read after, verify, record. Users: `gsc_submit_sitemap` (auto), `content_set_meta_description` (auto when empty, approval otherwise, validated per the content brief), `ga4_create_key_event` (approval, idempotent), `repo_open_pr` (approval, idempotent per day) |
+| Content | `gwo-content-brief` playbook: Hebrew SEO rules and answer-engine citation practices; scan rules aware of Hebrew vs Latin description lengths |
+| Scheduling | Worker with escalation rules in code (page broken, noindex gained, canonical lost, tracking lost, host split, crawler blocked, sitemap shrunk or unreachable), a written report per run, exit codes for schedulers, optional email delivery through Resend, Windows Task Scheduler installer |
+| Hosts | Claude Code plugin (8 skills, 6 commands) and Codex (AGENTS.md, config template) generated from one playbook set; CI fails on a hand edit |
+| Quality | Typecheck, unit tests for every pure module and every write path (with fakes), smoke test of the MCP server; CI on push |
+
+## 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
+```
+
+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.
+
+## 6. Risk classes
+
+| Class | Gate |
+|---|---|
+| `auto` | none |
+| `approval_required` | token `<site_id>:<action>` in-session |
+| `protected` | never |
+
+`policies/default.yaml`; site overrides may only tighten.
+
+## 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
+
+29 tools. Reads: `ops_*`, `web_*`, `google_*`, `gsc_*`, `ga4_*`, `gtm_*`, `site_*`, `pagespeed_check`. Writes: `gsc_submit_sitemap`, `content_set_meta_description`, `ga4_create_key_event`, `repo_open_pr`.
+
+## 9. Data model
+
+`sites/<host>.yaml` and gitignored `<host>.secrets.yaml`; `.gwo-data/<site_id>/{latest-scan.json, snapshots/, gtm/, audit.jsonl}`; `.gwo-data/_runs/` for worker reports; `secrets/` for the OAuth client and token.
+
+## 10. Security
+
+See `docs/SECURITY.md`. Additions in v0.3: Resend and GitHub tokens by environment only; scheduled tasks run as the operator's Windows user because the token store is DPAPI-bound; the GitHub token is fine-grained and scoped to the site repositories.
+
+## 11. Pilot status
+
+Both pilot sites (`aiguru.co.il`, `doritgrinberg.co.il`) are scanned daily, their Google properties are read live, and the first verified write (sitemap submission for aiguru) is in the audit log. Both are at near-zero organic traffic; operations on them is building presence, not optimising it. 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 for delivery and pull requests.
+
+## 12. v0.4 targets
+
+Tag Manager staged writes in a dedicated workspace with diff and approval-gated publish; title and JSON-LD writes through the adapters; Odoo structured-data injection; client report rendering to a document; an accessibility rule area (IS 5568) in the scanner; rendered-DOM checks with Playwright for JavaScript-heavy sites; a hosted worker so operations do not depend on one machine.

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

@@ -0,0 +1,92 @@
+# Google Web Operations: Product and Technical Specification v0.4
+
+Supersedes v0.3 (kept for history). v0.4 adds the write capabilities the playbooks were already asking for: Tag Manager changes staged, diffed and published under two gates; titles and structured data written through the site adapters; and a measurement playbook that tells both hosts how to use them.
+
+## 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.4 delivers
+
+| Area | Delivered |
+|---|---|
+| 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 | 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 | 81 tests: 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
+```
+
+`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
+
+44 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
+
+`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.5 targets
+
+An accessibility rule area (IS 5568) in the scanner; rendered-DOM checks with Playwright for JavaScript-heavy sites; a hosted worker so operations do not depend on one machine; product pages in the Odoo adapter when a client needs them.

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

@@ -0,0 +1,94 @@
+# Google Web Operations: Product and Technical Specification v0.5
+
+Supersedes v0.4 (kept for history). v0.5 makes the system installable: one npm package, one `gwo install` for both hosts, operator state outside the package. It also carries what landed after v0.4 was written: setup and site administration from the chat, the monthly client report as a Word document, and per-site decisions the scanner respects.
+
+## 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.5 delivers (cumulative since v0.3)
+
+| Area | Delivered |
+|---|---|
+| 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 | 89 tests: 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
+
+44 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.6 targets
+
+Rendered-DOM checks with Playwright for JavaScript-heavy sites; a hosted worker so operations do not depend on one machine; product pages in the Odoo adapter when a client needs them.