@aiguru/google-web-operations 0.6.4

package/packages/playbooks/50-onboarding.md

@@ -0,0 +1,25 @@
+---
+name: gwo-onboarding
+description: Bring a new site into operations. Registers it, captures a baseline scan, records the access the client granted, and produces the starting-point report.
+---
+
+# Onboarding a site
+
+Goal: a registry entry, a baseline, and a clear picture of what the client granted and what is still missing.
+
+## Steps
+
+1. **Register.** `ops_add_site` with the URL, name and platform (and for Odoo the ERP url and database). It writes `sites/<host>.yaml` with defaults; Google ids stay null until access is granted, then `google_discover_apply` fills them (gwo-setup).
+2. **Baseline.** `web_scan_site` at `maxPages` 200. This is the "before" picture. Note the severity counts in the onboarding record.
+3. **Access checklist.** The client adds the company operations Google account to:
+   - Search Console: Full permission on the domain property.
+   - Analytics: Editor on the GA4 property (Administrator if configuration changes are in scope). Record the numeric property id in the site file.
+   - Tag Manager: Publish permission on the container, if one exists.
+   Record what was granted and on what date (`ops_update_site` on `notes`, or the site's contacts). The operations account address comes from `ops_setup_status`.
+4. **Write path.** Confirm how the site can be changed: Odoo credentials in `sites/<host>.secrets.yaml`, or a repository path and branch. Test one read through the adapter before declaring the site `full` tier.
+5. **Measurement.** Run the audit in gwo-measurement. If the baseline shows no analytics, that is the first task: the client creates the container and grants Publish, then you stage the standard stack. If a container exists, `gtm_workspaces` shows whether the client has unpublished work; ask before staging next to it. Nothing else works without measurement.
+6. **Starting-point report.** From the gwo-client-report-template: where the site stands, the first three things that will be fixed, what is needed from the client.
+
+## Done when
+
+The site file is complete, a baseline snapshot exists, the access checklist has dates, and the operator has seen the starting-point report.

package/packages/playbooks/60-content-brief.md

@@ -0,0 +1,58 @@
+---
+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.
+---
+
+# 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.

package/packages/playbooks/70-measurement.md

@@ -0,0 +1,90 @@
+---
+name: gwo-measurement
+description: Measurement operations on Tag Manager and GA4. The standard stack per client, how to audit it, and the stage-diff-publish protocol for every container change. Load before touching Tag Manager or key events.
+---
+
+# Measurement
+
+Goal: every client site reports the same few things, reliably, without you ever editing a container by hand or publishing something nobody reviewed.
+
+## The standard stack
+
+One Tag Manager container per site, one GA4 property, and inside the container:
+
+| Entity | Name | Type | Fires on |
+|---|---|---|---|
+| Google tag | `Google tag - GA4` | `googtag` | All Pages |
+| Event tag | `GA4 - Event - generate_lead` | `gaawe` | the lead trigger |
+| Event tag | `GA4 - Event - <name>` | `gaawe` | one trigger per event |
+| Trigger | `Form - submit success` | `formSubmission` or `customEvent` | the site's form |
+| Trigger | `Click - phone` | `linkClick` filtered on `tel:` | phone links |
+| Trigger | `Click - WhatsApp` | `linkClick` filtered on `wa.me` | WhatsApp links |
+| Variable | `GA4 measurement id` | `c` (constant) | holds `G-...` |
+
+Names are prefixed by product and kind so a container full of a client's own tags still reads at a glance. Events use GA4's recommended names: `generate_lead`, `contact`, `sign_up`, `purchase`. The site's `conversions.primary_event` names the one that becomes a key event.
+
+Consent: Israeli sites do not need a consent banner for analytics today, but a client selling into the EU does. If the site has a consent tool, the Google tag must fire on `Consent Initialization - All Pages` with consent defaults; do not stage analytics tags that bypass it.
+
+## Audit (weekly step, onboarding step 5)
+
+1. `web_inspect_url` on the homepage: is exactly one `GTM-` container on the page, and is the `G-` id inside the container rather than hardcoded next to it? Two Google tags double-count.
+2. `gtm_snapshot`: tags, what fires them, which are paused. A paused tag that carries a key event is an outage.
+3. `gtm_workspaces`: is there a workspace with changes nobody published? Ask the client before touching it; it may be work in progress.
+4. `ga4_key_events` against `conversions.primary_event`. Missing means attribution is off for every report.
+5. `ga4_realtime` while you submit the site's own test form (or ask the operator to): the event must arrive within a minute with the expected name.
+
+## Change protocol
+
+Every container change, no exceptions:
+
+1. **Stage.** `gtm_stage` with the entities. Nothing is live yet. The tool creates or reuses the `gwo-` workspace, writes each entity as its own verified write, and returns the diff against the live version plus a **review token**.
+2. **Show the diff.** Present `gtm_workspace_diff` output to the operator: added, updated (with the fields), deleted. This is the moment to catch a wrong trigger.
+3. **Publish only with both tokens.** `gtm_publish` needs the approval token for `gtm.publish` and the review token. The review token is computed from the exact set of staged changes and the live version id; if anything moved since the operator looked, it will not match, and the publish is refused with a message saying to diff again.
+4. **Verify.** After publish: `gtm_versions` shows the new version, `web_inspect_url` still shows the container, `ga4_realtime` shows the event on a test action.
+
+What you never do: create tags outside the `gwo-` workspace, publish a workspace whose diff you have not presented, delete a tag (pause it instead; deletion is protected), or touch a workspace the client owns.
+
+## Entity bodies
+
+`gtm_stage` takes GTM API resources without ids. Trigger names may be used in `firingTriggerId`; the tool resolves them.
+
+Google tag:
+```json
+{ "kind": "tag", "body": { "name": "Google tag - GA4", "type": "googtag", "firingTriggerId": ["All Pages"],
+  "parameter": [{ "type": "template", "key": "tagId", "value": "G-XXXXXXX" }] } }
+```
+
+GA4 event tag:
+```json
+{ "kind": "tag", "body": { "name": "GA4 - Event - generate_lead", "type": "gaawe", "firingTriggerId": ["Form - submit success"],
+  "parameter": [{ "type": "template", "key": "eventName", "value": "generate_lead" },
+                { "type": "template", "key": "measurementIdOverride", "value": "G-XXXXXXX" }] } }
+```
+
+Form trigger (site pushes `form_submit` to the data layer on success):
+```json
+{ "kind": "trigger", "body": { "name": "Form - submit success", "type": "customEvent",
+  "customEventFilter": [{ "type": "equals", "parameter": [{ "type": "template", "key": "arg0", "value": "{{_event}}" }, { "type": "template", "key": "arg1", "value": "form_submit" }] }] } }
+```
+
+Phone click trigger:
+```json
+{ "kind": "trigger", "body": { "name": "Click - phone", "type": "linkClick",
+  "filter": [{ "type": "startsWith", "parameter": [{ "type": "template", "key": "arg0", "value": "{{Click URL}}" }, { "type": "template", "key": "arg1", "value": "tel:" }] }],
+  "waitForTags": { "type": "boolean", "value": "false" }, "checkValidation": { "type": "boolean", "value": "false" } } }
+```
+
+Pause a tag (update by name, merge):
+```json
+{ "kind": "tag", "body": { "name": "Old UA tag", "paused": true } }
+```
+
+Built-in variables such as `{{Click URL}}` must be enabled in the container; if a trigger fails to compile on publish, that is the usual reason. Say so and propose enabling it in the UI.
+
+## Key events
+
+`ga4_create_key_event` for `conversions.primary_event` needs the token for `ga4.key_event.create` and the `analytics.edit` scope. It is idempotent. Do not mark more than three events as key events on a small site; every extra one dilutes the reports.
+
+## When the client publishes
+
+A new version you did not create (daily step) is not a fault. `gtm_snapshot` then `gtm_diff`: if a key-event tag was removed or paused, escalate as tracking-lost. Otherwise record it and move on.

package/packages/playbooks/80-setup.md

@@ -0,0 +1,40 @@
+---
+name: gwo-setup
+description: Set up and administer Google Web Operations from the chat. Connect the Google Cloud project, authorise the operations account, register sites, fill in Google ids, record site decisions. Load when the operator asks to connect, add, configure or "set up" anything.
+---
+
+# Setup and administration
+
+Everything here changes this system's own configuration, never a client site. Start every setup conversation with `ops_setup_status`: it says what is connected, what each site is missing, and the next step. Do the next step, then call it again. Stop when `nextSteps` holds only optional items.
+
+## Connecting Google (once per installation)
+
+1. **Cloud project.** The operator creates or reuses one Google Cloud project for all client sites (the pilot uses "Google Web Operations" under the company Workspace). In it: enable the Search Console API, Google Analytics Data API, Google Analytics Admin API, Tag Manager API and PageSpeed Insights API; set the OAuth consent screen to Internal; create an OAuth client of type **Desktop app** and download its JSON. Give these steps as a short checklist; do not open the browser for them.
+2. **Install the client.** Ask for the path of the downloaded JSON and call `google_setup_oauth_client` with it. Never ask the operator to paste the file's contents into the chat.
+3. **Authorise.** `google_auth_login`. A browser tab opens; the operator signs in with the dedicated operations account (not a personal one) and consents. The tool waits about a minute and then returns; if consent takes longer, `ops_setup_status` shows when the token is stored.
+4. **Write scopes** are separate and deliberate: `google_auth_login` with `["ga4_write"]` before key events, `["gtm_edit", "gtm_publish"]` before Tag Manager changes. Do not request them until the operator wants those writes.
+
+## Registering a site
+
+Ask only for what cannot be inferred: the site URL, the client's name, the platform (Odoo, Next.js, WordPress, other), and for Odoo the ERP URL and database name. Everything else has a default (Hebrew, full tier, `generate_lead`, adapter from platform). Then:
+
+1. `ops_add_site`. It writes `sites/<host>.yaml` with the same layout as every other site.
+2. `web_scan_site` at 50 pages: the baseline, and the first thing the operator sees about the site.
+3. Access checklist for the client, in one message they can forward: add the operations account to Search Console (Full), GA4 (Editor), Tag Manager (Publish) if there is a container. The account's address comes from `ops_setup_status`.
+4. When the client confirms: `google_discover_apply`. It matches properties to sites by host and writes the ids. Matches by name only are reported, never written; confirm those with the operator and set them with `ops_update_site`.
+5. For Odoo: the operator creates the API user and puts `odoo.login` and `odoo.api_key` into `sites/<host>.secrets.yaml` by hand. Then `site_adapter_ping`. For a repository site: `ops_update_site` with `write.repo.local_path`, then `site_adapter_ping`.
+6. `ops_setup_status` until the site's `missing` list is empty or only optional.
+
+## Changing a site
+
+- One field: `ops_update_site` with the dotted path (`google.tag_manager.public_id`, `contacts.report_to`, `cadence.weekly`, `enabled`). Values that look like JSON are parsed; the rest are strings.
+- A site decision: `ops_add_suppression` with the rule, the path if page-specific, and the reason in the client's words (gwo-operating-model, "Findings are not all faults").
+- Never from chat: `site_id`, anything under `policy`, and any credential. Say so and describe the manual edit.
+
+## Environment
+
+`.env` at the repository root, read on every start. `ops_setup_status` shows which are set. Report delivery needs `RESEND_API_KEY`, `GWO_REPORT_FROM`, `GWO_REPORT_TO`; pull requests need `GITHUB_TOKEN`; client reports in the company template need `GWO_DOCX_TEMPLATE`. The operator edits the file; values are never typed into the chat.
+
+## Scheduling
+
+Windows: `powershell -ExecutionPolicy Bypass -File tools\schedule.ps1 install` registers the daily and weekly runs; `status` shows them. The tasks run as the operator's Windows user because the Google token is bound to that user.

package/packages/playbooks/90-client-report-template.md

@@ -0,0 +1,34 @@
+---
+name: gwo-client-report-template
+description: Structure and tone for the client-facing monthly report. Plain language, three questions, one small table.
+---
+
+# 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/packages/policy/src/index.js

@@ -0,0 +1,115 @@
+/**
+ * Policy engine.
+ *
+ * Two responsibilities, deliberately separate:
+ *   classify()  answers "what class is this action for this site?"
+ *   enforce()   throws unless the action may proceed right now.
+ *
+ * Classification is data (policies/default.yaml plus site overrides).
+ * Enforcement is the one place execution can be stopped, so every write
+ * path must call it. A host prompt cannot downgrade a class; the only way
+ * past approval_required is a token the operator produces in-session.
+ */
+import { readFileSync } from 'node:fs';
+import { parse } from 'yaml';
+import { POLICY_FILE } from "../../core/src/paths.js";
+const ORDER = ['auto', 'approval_required', 'protected'];
+let cache;
+export function policy() {
+    if (!cache)
+        cache = parse(readFileSync(POLICY_FILE, 'utf8'));
+    return cache;
+}
+/** For tests: drop the cached policy so a changed file is re-read. */
+export function resetPolicyCache() { cache = undefined; }
+function matchList(list, action) {
+    if (!list?.length)
+        return null;
+    if (list.includes(action))
+        return 'exact';
+    // Longest prefix wins among prefix matches; caller compares classes.
+    return list.some((item) => action.startsWith(item + '.')) ? 'prefix' : null;
+}
+function stricter(a, b) {
+    return ORDER.indexOf(a) >= ORDER.indexOf(b) ? a : b;
+}
+/** Resolve the risk class of an action, applying site overrides (tighten only). */
+export function classify(action, site) {
+    const p = policy();
+    let risk = p.default;
+    let source = 'default';
+    // Exact matches take priority over prefix matches; among prefix matches
+    // the most restrictive class wins so a broad "auto" cannot shadow a
+    // narrower "protected".
+    const lists = [
+        ['protected', p.protected], ['approval_required', p.approval_required], ['auto', p.auto],
+    ];
+    let exact = null;
+    let prefix = null;
+    for (const [cls, list] of lists) {
+        const m = matchList(list, action);
+        if (m === 'exact' && exact === null)
+            exact = cls;
+        if (m === 'prefix')
+            prefix = prefix === null ? cls : stricter(prefix, cls);
+    }
+    if (exact) {
+        risk = exact;
+        source = 'exact';
+    }
+    else if (prefix) {
+        risk = prefix;
+        source = 'prefix';
+    }
+    // Site overrides can only raise the class.
+    const o = site?.policy?.overrides;
+    if (o?.protected?.includes(action) || o?.protected?.some((x) => action.startsWith(x + '.'))) {
+        if (risk !== 'protected') {
+            risk = 'protected';
+            source = 'site';
+        }
+    }
+    else if (o?.approval_required?.includes(action) || o?.approval_required?.some((x) => action.startsWith(x + '.'))) {
+        if (risk === 'auto') {
+            risk = 'approval_required';
+            source = 'site';
+        }
+    }
+    const reason = {
+        auto: 'Autonomous by policy.',
+        approval_required: 'Requires an operator approval token in this session.',
+        protected: 'Protected by policy. Cannot be enabled per site or by instruction.',
+    }[risk];
+    return { action, risk, source, reason };
+}
+/** Deterministic, human-readable approval token. */
+export function approvalToken(siteId, action) {
+    return `${siteId}:${action}`;
+}
+export class PolicyError extends Error {
+    decision;
+    constructor(decision, message) {
+        super(message);
+        this.name = 'PolicyError';
+        this.decision = decision;
+    }
+}
+/**
+ * Throw unless the action may proceed. Call this at the top of every write.
+ * @param approval token supplied by the operator, if any
+ */
+export function enforce(site, action, { approval } = {}) {
+    const d = classify(action, site);
+    if (d.risk === 'protected') {
+        throw new PolicyError(d, `[protected] ${action}: ${d.reason}`);
+    }
+    if (d.risk === 'approval_required') {
+        const expected = approvalToken(site.site_id, action);
+        if (approval !== expected) {
+            throw new PolicyError(d, `[approval_required] ${action}: ${d.reason} Expected token "${expected}".`);
+        }
+    }
+    return d;
+}
+export function limits() { return policy().limits ?? {}; }
+export function writeRules() { return policy().write_rules ?? {}; }

package/packages/storage/src/index.js

@@ -0,0 +1,131 @@
+/**
+ * Per-site persistent state under .gwo-data/<site_id>/.
+ *
+ *   latest-scan.json       most recent full scan
+ *   snapshots/<ts>.json    fingerprints for change detection
+ *   audit.jsonl            append-only operational log (runs, writes, blocks)
+ *
+ * Nothing here is secret. Nothing here is committed.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { DATA_DIR } from "../../core/src/paths.js";
+function siteDir(siteId) {
+    const d = path.join(DATA_DIR, siteId);
+    mkdirSync(path.join(d, 'snapshots'), { recursive: true });
+    return d;
+}
+const stamp = () => new Date().toISOString().replace(/[:.]/g, '-');
+// ---------------------------------------------------------------- scans
+export function saveScan(scan) {
+    const d = siteDir(scan.siteId);
+    const scanPath = path.join(d, 'latest-scan.json');
+    const snapshotPath = path.join(d, 'snapshots', `${stamp()}.json`);
+    writeFileSync(scanPath, JSON.stringify(scan, null, 2));
+    writeFileSync(snapshotPath, JSON.stringify(fingerprint(scan), null, 2));
+    return { scanPath, snapshotPath };
+}
+export function loadScan(siteId) {
+    const f = path.join(siteDir(siteId), 'latest-scan.json');
+    return existsSync(f) ? JSON.parse(readFileSync(f, 'utf8')) : null;
+}
+// ---------------------------------------------------------------- snapshots
+export function listSnapshots(siteId) {
+    return readdirSync(path.join(siteDir(siteId), 'snapshots')).filter((f) => f.endsWith('.json')).sort();
+}
+export function loadSnapshot(siteId, name) {
+    const f = path.join(siteDir(siteId), 'snapshots', name);
+    return existsSync(f) ? JSON.parse(readFileSync(f, 'utf8')) : null;
+}
+/** Reduce a scan to the fields that matter for change detection. */
+export function fingerprint(scan) {
+    const pages = {};
+    for (const p of scan.pages) {
+        const s = p.signals;
+        pages[p.url] = {
+            status: p.status,
+            title: s?.title ?? null,
+            description: s?.description ?? null,
+            canonical: s?.canonicalAbs ?? null,
+            noindex: s?.noindex ?? false,
+            h1: s?.headings.h1[0] ?? null,
+            jsonldTypes: s?.jsonldTypes ?? [],
+            ga4: s?.analytics.ga4 ?? [],
+            gtm: s?.analytics.gtm ?? [],
+            wordCount: s?.wordCount ?? 0,
+        };
+    }
+    return {
+        at: scan.at,
+        origin: scan.origin,
+        sitemapCount: scan.sitemap.count,
+        findingsBySeverity: scan.summary,
+        findingIds: scan.findings.map((f) => `${f.id}|${f.url ?? ''}`).sort(),
+        pages,
+    };
+}
+/** What changed between two snapshots. */
+export function diffSnapshots(before, after) {
+    const out = { newFindings: [], resolvedFindings: [], pageChanges: [], addedPages: [], removedPages: [] };
+    const bIds = new Set(before.findingIds), aIds = new Set(after.findingIds);
+    for (const id of aIds)
+        if (!bIds.has(id))
+            out.newFindings.push(id);
+    for (const id of bIds)
+        if (!aIds.has(id))
+            out.resolvedFindings.push(id);
+    const SCALAR = ['status', 'title', 'description', 'canonical', 'noindex', 'h1'];
+    const LISTS = ['jsonldTypes', 'ga4', 'gtm'];
+    for (const [url, a] of Object.entries(after.pages)) {
+        const b = before.pages[url];
+        if (!b) {
+            out.addedPages.push(url);
+            continue;
+        }
+        const changes = [];
+        for (const k of [...SCALAR, ...LISTS]) {
+            if (JSON.stringify(b[k]) !== JSON.stringify(a[k]))
+                changes.push({ field: k, before: b[k], after: a[k] });
+        }
+        // Word count: only flag material moves, not copy edits.
+        const delta = Math.abs(a.wordCount - b.wordCount);
+        if (delta > Math.max(100, b.wordCount * 0.3))
+            changes.push({ field: 'wordCount', before: b.wordCount, after: a.wordCount });
+        if (changes.length)
+            out.pageChanges.push({ url, changes });
+    }
+    for (const url of Object.keys(before.pages))
+        if (!after.pages[url])
+            out.removedPages.push(url);
+    return out;
+}
+// ---------------------------------------------------------------- named snapshots (gtm, ga4-config, ...)
+/** Save a dated record under .gwo-data/<site>/<kind>/<ts>.json. Returns the file name. */
+export function saveNamed(siteId, kind, data) {
+    const d = path.join(siteDir(siteId), kind);
+    mkdirSync(d, { recursive: true });
+    const name = `${stamp()}.json`;
+    writeFileSync(path.join(d, name), JSON.stringify(data, null, 2));
+    return name;
+}
+export function listNamed(siteId, kind) {
+    const d = path.join(siteDir(siteId), kind);
+    return existsSync(d) ? readdirSync(d).filter((f) => f.endsWith('.json')).sort() : [];
+}
+export function loadNamed(siteId, kind, name) {
+    const f = path.join(siteDir(siteId), kind, name);
+    return existsSync(f) ? JSON.parse(readFileSync(f, 'utf8')) : null;
+}
+// ---------------------------------------------------------------- audit log
+export function appendAudit(record) {
+    const full = { at: new Date().toISOString(), ...record };
+    appendFileSync(path.join(siteDir(record.siteId), 'audit.jsonl'), JSON.stringify(full) + '\n');
+    return full;
+}
+export function readAudit(siteId, { limit = 50 } = {}) {
+    const f = path.join(siteDir(siteId), 'audit.jsonl');
+    if (!existsSync(f))
+        return [];
+    const lines = readFileSync(f, 'utf8').trim().split('\n').filter(Boolean);
+    return lines.slice(-limit).map((l) => JSON.parse(l));
+}

package/policies/default.yaml

@@ -0,0 +1,90 @@
+# Policy profile: standard-client-site
+#
+# Single source of truth for what the agent may do. Enforced by
+# packages/policy on both hosts. A site's policy.overrides may move an
+# action UP a class (auto -> approval_required -> protected) but never down.
+#
+# Action ids are dotted and hierarchical. A rule for "web.read" also covers
+# "web.read.metadata". Exact matches win over prefix matches.
+
+profile: standard-client-site
+version: 2
+
+# Anything not listed below.
+default: approval_required
+
+# Read-only, or reversible with a tiny blast radius.
+auto:
+  - web.read
+  - web.scan
+  - web.diff
+  - google.read
+  - gsc.read
+  - ga4.read
+  - gtm.read
+  - pagespeed.read
+  - audit.write
+  - report.write
+  - gsc.sitemap.submit
+  - content.meta_description.fill_empty   # only when the field is empty
+  # This system's own configuration, never a client site. Recorded in the audit log.
+  - registry.site.create
+  - registry.site.update                  # site_id, policy and credentials are refused in code
+  - google.auth.setup
+  - google.auth.login
+
+# Requires an approval token "<site_id>:<action>" in the same session.
+approval_required:
+  - content.write
+  - content.title.update
+  - content.meta_description.update
+  - content.schema.update
+  - content.canonical.update
+  - content.robots.update
+  - content.redirect.update
+  - sitemap.update
+  - gtm.stage
+  - gtm.publish
+  - ga4.key_event.create
+  - ga4.config.update
+  - github.pr.create
+  - cloudflare.config.update
+
+# Never executed by the agent. Not even with a token.
+protected:
+  - google.property.delete
+  - gtm.container.delete
+  - gsc.site.delete
+  - gtm.workspace.delete_with_changes
+  - ga4.data_retention.update
+  - analytics.data.delete
+  - access.user.remove
+  - billing
+  - account
+  - dns.destructive
+  - content.delete
+  - legal.update
+  - privacy.update
+  - auth.security.update
+
+# Rules that shape how writes are performed, regardless of class.
+write_rules:
+  verify_after_write: true          # every write is followed by a read that confirms it
+  record_previous_value: true       # audit record carries the before state
+  gtm:
+    always_use_workspace: true
+    workspace_name_prefix: gwo-
+    require_diff_before_publish: true
+  content:
+    dry_run_by_default: true
+    max_pages_per_run: 25
+
+# Operational limits.
+limits:
+  crawl:
+    max_pages_per_scan: 200
+    concurrency: 4
+    politeness_delay_ms: 250
+  search_console:
+    queries_per_minute_per_user: 180
+    max_rows_per_query: 25000

package/sites/schema.yaml

@@ -0,0 +1,71 @@
+# Site registry record. One file per site: sites/<host>.yaml
+# Credentials go in sites/<host>.secrets.yaml (gitignored), never here.
+#
+# Required: site_id, name, production_url. Everything else has a default.
+
+site_id: example                    # short stable id, used in tokens and data paths
+name: Example Ltd
+enabled: true
+production_url: https://example.co.il
+alt_hosts:                          # variants that must redirect to production_url
+  - https://www.example.co.il
+locales: [he, en]
+default_locale: he
+timezone: Asia/Jerusalem
+platform: odoo                      # odoo | nextjs | wordpress | custom
+tier: full                          # full: we can change the site. advisory: report only.
+
+seo:
+  sitemap: /sitemap.xml
+  robots: /robots.txt
+  trailing_slash: false
+
+google:
+  search_console:
+    property: sc-domain:example.co.il     # or a URL-prefix property
+  ga4:
+    measurement_id: G-XXXXXXXXXX          # visible in page source
+    property_id: "123456789"              # numeric; needed for Data/Admin API
+  tag_manager:
+    public_id: GTM-XXXXXXX
+    account_id: null
+    container_id: null
+
+write:
+  adapter: odoo                     # odoo | repo | none  (see docs/SITE-ADAPTERS.md)
+  odoo:                             # when adapter is odoo; login + api_key go in <host>.secrets.yaml
+    url: https://erp.example.co.il
+    db: example_prod
+    website_id: null                # set for multi-website databases
+  repo:                             # when adapter is repo; the checkout must contain gwo.seo.json
+    url: null
+    branch: main
+    local_path: null
+
+conversions:
+  primary_event: generate_lead
+
+findings:                           # site decisions the scanner respects; each needs a reason
+  suppress:
+    - rule: measurement.no-gtm      # exact rule id, or "area.*" for a whole area
+      reason: Owner requires GA4 without Tag Manager.
+    - rule: content.thin
+      path: /contact/               # optional: exact path, or a prefix ending in "*"
+      reason: Conversion page, intentionally short.
+
+policy:
+  profile: standard-client-site
+  overrides:                        # may only tighten the shared policy
+    approval_required: []
+    protected: []
+
+cadence:
+  daily: true
+  weekly: true
+  monthly: true
+
+contacts:
+  owner: Owner Name
+  report_to: []
+
+notes: Free text for the operator.