@friedbotstudio/create-baseline 0.5.0 → 0.7.0

package/src/seed.template.md

@@ -11,7 +11,7 @@
 
 **Mandatory binding language.** Each numbered section (§) below specifies a binding requirement for the baseline. Implementations SHALL conform; `CLAUDE.md` Articles SHALL reference the corresponding §; project amendments (per `CLAUDE.md` Art. X) SHALL NOT contradict any § here.
 
-The baseline turns soft engineering rules (no unauthorized commits, no stubs, no mocks of internal code, no self-approved specs) into structural guarantees enforced by write-boundary hooks. Eleven workflow phases plus one stripped-down chore track (skips TDD; runs verify + archive mandatorily, simplify/integrate/document conditionally), seventeen write/run-boundary guards plus four lifecycle hooks plus one input-boundary hook (twenty-two hook scripts total — twenty `.sh` + two `.mjs` after the JS-port pilot), thirty-seven skills, one subagent, and four consent gates. Decisions live in main context; the lone subagent (`swarm-worker`) executes pre-decided recipes in parallel worktrees during `/swarm-dispatch`. Every artifact is archived; every third-party API is looked up against live docs. Project memory accumulates across sessions in `.claude/memory/` — auto-extracted by a Stop hook, curated in main context via `/memory-flush`, self-healing via re-verification.
+The baseline turns soft engineering rules (no unauthorized commits, no stubs, no mocks of internal code, no self-approved specs) into structural guarantees enforced by write-boundary hooks. Eleven workflow phases plus one stripped-down chore track (skips TDD; runs verify + archive mandatorily, simplify/integrate/document conditionally), seventeen write/run-boundary guards plus four lifecycle hooks plus one input-boundary hook (twenty-two hook scripts total — twenty `.sh` + two `.mjs` after the JS-port pilot), thirty-eight skills, one subagent, and four consent gates. Decisions live in main context; the lone subagent (`swarm-worker`) executes pre-decided recipes in parallel worktrees during `/swarm-dispatch`. Every artifact is archived; every third-party API is looked up against live docs. Project memory accumulates across sessions in `.claude/memory/` — auto-extracted by a Stop hook, curated in main context via `/memory-flush`, self-healing via re-verification.
 
 ---
 
@@ -110,7 +110,7 @@ Applies to every language. Mappings for TSX, Node, Python, Go, Rust ship inside
 │   │   └── lib/common.sh       # shared helpers
 │   ├── agents/                 # 1 subagent: swarm-worker (rendered from src/agents/swarm-worker.template.md)
 │   ├── commands/               # 5 consent/bootstrap gates (user-only — structurally)
-│   ├── skills/                 # 37 skills: artifact (4) + phases (11) + workers (5) + spec helpers (4) + orchestration (3) + memory (1) + shared globals (7) + audit (1) + alt tracks (1)
+│   ├── skills/                 # 38 skills: artifact (4) + phases (11) + workers (5) + spec helpers (4) + orchestration (3) + memory (1) + shared globals (7) + audit (1) + alt tracks (1) + maintenance (1)
 │   ├── memory/                 # project memory: 7 canonical files + _pending.md (gitignored body) + README.md
 │   └── state/                  # runtime: workflow.json, approvals, swarm plans, verdicts, logs
 ├── src/                        # pristine ship-time templates (overlay source for `npx @friedbotstudio/create-baseline`)
@@ -181,7 +181,7 @@ The baseline ships exactly one subagent. The architectural reason: subagents los
 
 **Automated re-rendering by `/init-project`.** Step 6.4 re-renders `swarm-worker.md` from the template, driven by the recommender's `additions.swarm_worker_skills`. The recommender does **not** propose new subagent types — only stack-skill additions for the existing worker. Specialization happens via skills loaded into the worker's context, not via parallel agent personas; new decision-making roles belong in skills, which run in main context.
 
-### §4.3 Skills (37)
+### §4.3 Skills (38)
 
 Each at `.claude/skills/<name>/SKILL.md`, frontmatter `name` + `description`, plus optional `template.md` (artifact skills) or helper scripts.
 
@@ -247,7 +247,7 @@ Each vendored shared global ships with its own `LICENSE` + `NOTICE` alongside th
 
 - `chore` — for tasks with no failing-test-driven code change (documentation, governance counts, vendored-skill content updates, configuration, formatting, typo fixes, dependency bumps, skill consolidations). Skips `/scenario` and `/implement` — there is nothing to drive with a failing test. Runs the edits directly, then conditionally invokes `simplify` / `integrate` / `document` based on what the diff touches (each has explicit triggers in the chore skill body). `verify`, `archive`, and `/grant-commit` + `/commit` always run. Chore is a stripped-down pipeline, **not** a bypass — silent skips of triggered conditional phases are forbidden; the end-of-chore summary documents every skip rationale. Tasks that need a real failing test route to `/tdd` or higher instead.
 
-### §4.4 Commands (4) — structurally user-only
+### §4.4 Commands (6) — structurally user-only
 
 Files at `.claude/commands/<name>.md`. Commands differ from skills in exactly one way: **Claude cannot invoke them via the Skill tool.** A command is a button only a human can press.
 
@@ -258,8 +258,9 @@ Files at `.claude/commands/<name>.md`. Commands differ from skills in exactly on
 | `grant-commit` | Opens a 5-minute consent window for `git commit` on a protected branch. Writes `.claude/state/commit_consent`. Enforced by `git_commit_guard`. |
 | `grant-push` | Opens a 5-minute consent window for `git push` on a protected branch. Writes `.claude/state/push_consent`. Enforced by `git_commit_guard`. Not a workflow-phase gate — a runtime consent for the branch-aware policy (§11). |
 | `init-project` | One-time bootstrap. Detects stack, proposes `.claude/project.json` (test cmd, lint cmd, TDD globs, destructive patterns, artifact required sections, swarm config). Flips `configured: true`. |
+| `init-project-doctor` | Detects baseline drift — missing/invalid `.claude/workflows.jsonl`, schema/invariant violations, four-way Article IV / §18 mirror drift, and (advisory) shipped-tooling files placed outside `.claude/`. Interactive: presents each violation via `AskUserQuestion` and applies the named fix on confirmation. |
 
-**Adding a sixth command requires answering yes to both:** "does a human need to press this?" and "is 'user-only via frontmatter flag' too weak a guarantee?" Otherwise make it a skill.
+**Adding a seventh command requires answering yes to both:** "does a human need to press this?" and "is 'user-only via frontmatter flag' too weak a guarantee?" Otherwise make it a skill.
 
 ### §4.5 MCP servers (3)
 
@@ -338,7 +339,7 @@ Phases are fixed ordering; `/triage` picks the entry and may mark phases as exce
 
 ## §6 — Consent model
 
-**Four consent gates + one bootstrap gate.** All are slash commands, not skills. Commands live in `.claude/commands/`; Claude cannot invoke them via the Skill tool. The guarantee is structural (file location), not flag-based. Three of the four gates are workflow-phase gates (A: `/approve-spec`, B: `/approve-swarm`, C: `/grant-commit`); the fourth (`/grant-push`) is a Bash-time consent for the branch-aware push policy in §11.
+**Four consent gates + one bootstrap + one doctor.** All are slash commands, not skills. Commands live in `.claude/commands/`; Claude cannot invoke them via the Skill tool. The guarantee is structural (file location), not flag-based. Three of the four gates are workflow-phase gates (A: `/approve-spec`, B: `/approve-swarm`, C: `/grant-commit`); the fourth (`/grant-push`) is a Bash-time consent for the branch-aware push policy in §11. The bootstrap is `/init-project`; the doctor is `/init-project doctor` (drift detector + repairer for `.claude/workflows.jsonl` + the §18 / Article IV four-way mirror; see §18.7).
 
 | Gate | When it fires | Unlocks |
 |---|---|---|
@@ -516,7 +517,7 @@ Seed-level requirement: no stale workflow artifacts in the working tree after co
 
 **Step 4:** Write `src/agents/swarm-worker.template.md` (canonical-body store, per §4.2) — the only subagent template. Then render `.claude/agents/swarm-worker.md` from it with default tokens. The template carries four tokens — `{{NAME}}`, `{{DESCRIPTION}}`, `{{SKILLS}}`, `{{ROLE_LINE}}`. Default `SKILLS` is the YAML list block `  - scenario\n  - implement` (the worker's two mandatory sub-skills). Render-parity holds at this stage. `/init-project` later re-renders the worker with stack-aware tokens when the recommender flags stack-specific skills to preload via `additions.swarm_worker_skills`.
 
-**Step 5:** Write `.claude/skills/` for the 37 skills (§4.3) — 29 workflow/worker/orchestration/memory/alt-track skills you author (the +1 over 28 is the `changelog` Phase 11.5 skill) plus 7 shared globals plus 1 audit skill. The breakdown: artifact drafting (4) + workflow phases (10) + phase workers (5: `scenario`, `implement`, `verify`, `prose`, `design-ui`) + spec helpers (4: `spec-lint`, `spec-render`, `spec-diagram-review`, `spec-traceability-review`) + orchestration (3: `harness`, `swarm-plan`, `swarm-dispatch`) + memory (1: `memory-flush`) + shared globals (7: `claude-automation-recommender`, `code-structure`, `humanizer`, `documentation`, `technical-tutorials`, `copywriting`, `impeccable`) + drift defender (1: `audit-baseline`) + alternate tracks (1: `chore`). The vendored `claude-automation-recommender` (Apache 2.0, from `claude-code-setup`), the writing/quality globals, and the design global ship unchanged with their licenses intact. Artifact skills (intake, brd, spec, rca) each ship a `template.md`. Helper scripts: swarm-plan gets `validate.sh`, swarm-dispatch gets `swarm_merge.sh`, spec-render gets `render.sh`, spec-lint gets `lint.sh`, archive gets `archive.sh`, audit-baseline gets `audit.sh`. All helper scripts `chmod +x`.
+**Step 5:** Write `.claude/skills/` for the 38 skills (§4.3) — 29 workflow/worker/orchestration/memory/alt-track skills you author (the +1 over 28 is the `changelog` Phase 11.5 skill) plus 7 shared globals plus 1 audit skill plus 1 maintenance skill. The breakdown: artifact drafting (4) + workflow phases (10) + phase workers (5: `scenario`, `implement`, `verify`, `prose`, `design-ui`) + spec helpers (4: `spec-lint`, `spec-render`, `spec-diagram-review`, `spec-traceability-review`) + orchestration (3: `harness`, `swarm-plan`, `swarm-dispatch`) + memory (1: `memory-flush`) + shared globals (7: `claude-automation-recommender`, `code-structure`, `humanizer`, `documentation`, `technical-tutorials`, `copywriting`, `impeccable`) + drift defender (1: `audit-baseline`) + alternate tracks (1: `chore`) + maintenance (1: `upgrade-project`). The vendored `claude-automation-recommender` (Apache 2.0, from `claude-code-setup`), the writing/quality globals, and the design global ship unchanged with their licenses intact. Artifact skills (intake, brd, spec, rca) each ship a `template.md`. Helper scripts: swarm-plan gets `validate.sh`, swarm-dispatch gets `swarm_merge.sh`, spec-render gets `render.sh`, spec-lint gets `lint.sh`, archive gets `archive.sh`, audit-baseline gets `audit.sh`. All helper scripts `chmod +x`.
 
 **Step 6:** Write `.claude/commands/*.md` for the 4 gates (§4.4). All carry `disable-model-invocation: true` as belt-and-braces; structural user-only is enforced by their directory.
 
@@ -598,3 +599,147 @@ The audit at `.claude/skills/audit-baseline/audit.sh` consumes `manifest.owners.
 The audit also verifies constitutional citation: CLAUDE.md SHALL contain the literal string "Article XI" and a reference to the manifest, and `docs/init/seed.md` SHALL contain "§17" and a manifest reference. Missing citations trigger FAIL with `CLAUDE.md missing Article XI citation` or `seed.md missing §17 citation`.
 
 This provenance system is intentionally minimal: the manifest tracks shipped-file hashes; the frontmatter declares per-skill ownership; the audit reconciles the two against on-disk reality. Cryptographic supply-chain attestation, signed lock files, and per-skill aggregate merkle hashes are non-goals; the per-file `manifest.files` map already covers every file in every skill directory. A future `npx @friedbotstudio/create-baseline upgrade` subcommand will consume `manifest.owners.skills` + `manifest.files` to safely re-overlay baseline-owned files while leaving user-added skills and locally-customized baseline skills untouched — that subcommand is out of scope here.
+
+---
+
+## §18 — Workflow definitions and Article IV invariants
+
+### 18.1 Source of truth
+
+`.claude/workflows.jsonl` is the canonical source for every workflow this baseline can execute. The file holds one Track record per line (JSONL). It is project-owned and `NEVER_TOUCH` (declared in `src/cli/install.js:NEVER_TOUCH` and `scripts/build-manifest.mjs:NEVER_TOUCH_PATHS`); baseline upgrades preserve user customizations verbatim via `NEVER_TOUCH_PRESERVE`. The shipped baseline overlays the pristine 6-track set from `src/.claude/workflows.template.jsonl` onto fresh installs via `scripts/build-template.sh` Stage 2; existing installs are not touched. The JSON Schema document at `.claude/schemas/workflow-track.v1.json` is referenced by `Track.$schema` and is itself `NEVER_TOUCH`.
+
+`workflows.jsonl` supersedes the hardcoded triage templates (intake-full / spec-entry / tdd-quickfix / chore). Triage reads `workflows.jsonl` at seed time, validates each Track, classifies the user's request, and materializes the chosen Track's DAG into the TaskList. The canonical four tracks shipped in the pristine template are byte-equivalent to the pre-§18 hardcoded templates per spec AC-016 (`tests/byte-equivalent-migration.test.mjs`).
+
+### 18.2 Track schema
+
+A **Track** record has this shape (full definition in `.claude/schemas/workflow-track.v1.json`):
+
+```jsonc
+{
+  "$schema": "./schemas/workflow-track.v1.json",
+  "track_id": "<unique-across-file>",
+  "name": "<short label>",
+  "description": "<paragraph; read by the LLM classifier>",
+  "selectable": true,            // false = sub-track only (referenced via sub_track)
+  "selector_hints": ["<descriptive phrase>", ...],
+  "preconditions": [{"name": "<predicate>", "argument": "<opt>"}, ...],
+  "invariants": ["commits", "requires_spec", ...],
+  "nodes": [Node, ...]
+}
+```
+
+A **Node** is either a `task` (skill invocation or sub-track expansion) or a `selector` (picks one of multiple alternates at runtime):
+
+```jsonc
+{
+  "id": "<unique-within-track>",
+  "type": "task" | "selector",
+  // type=task → exactly one of:
+  "skill": "<skill-or-command-name>",
+  "sub_track": "<another-track_id>",
+  // type=selector → required:
+  "alternates": [Alternate, ...],
+  // shared:
+  "input": "<opt; passed to the skill at invocation>",
+  "invocation_prompt": "<opt; declared-now/used-later — v2 Handlebars+LLM>",
+  "output": "<opt; informational artifact path>",
+  "output_formatter_prompt": "<opt; declared-now/used-later>",
+  "depends_on": ["<predecessor node id>", ...],
+  "blocks": ["<successor node id>", ...],
+  "can_parallel": false,         // true: peers at same dep level dispatch concurrently
+  "needs_user": false,           // true: consent gate; harness yields
+  "activeForm": "<TaskList spinner text>",
+  "metadata": {"phase": "<...>"}
+}
+```
+
+An **Alternate** (inside a selector node):
+
+```jsonc
+{
+  "skill": "<skill-name>",       // XOR with sub_track
+  "sub_track": "<track_id>",     // XOR with skill
+  "preconditions": [Predicate, ...],
+  "description": "<rationale>"
+}
+```
+
+A **Predicate** (track-level and alternate-level):
+
+```jsonc
+{
+  "name": "<v1-vocabulary>",
+  "argument": "<opt; e.g., '3' for min_components>"
+}
+```
+
+### 18.3 Article IV invariants (I1..I11)
+
+Every Track in `workflows.jsonl` SHALL satisfy these invariants. Validation runs at three points: install/upgrade time (audit-baseline), triage time (LLM-driven selector), and harness time (per-node before dispatch).
+
+- **I1.** Unique `track_id` across the file.
+- **I2.** Unique `node.id` within a track.
+- **I3.** `type=task` nodes carry exactly one of `{skill, sub_track}`. `type=selector` nodes carry non-empty `alternates[]`.
+- **I4.** Every `depends_on` and `blocks` reference resolves to a `node.id` in the same track.
+- **I5.** The dependency DAG is acyclic.
+- **I6.** Tracks declaring the `commits` invariant SHALL include a `needs_user: true` `grant-commit` node ordered before the node with `skill: "commit"`.
+- **I7.** Every `sub_track` reference resolves to a Track with `selectable: false`.
+- **I8.** Every `skill:` reference resolves to a known invokable — skill in `EXPECTED_SKILLS ∪ project.json additions.skills`, OR consent-gate command in `.claude/commands/` (e.g., `approve-spec`, `grant-commit`, `approve-swarm`).
+- **I9.** `needs_user: true` nodes appear in dependency order before any node that depends on their consent.
+- **I10.** A selector node's alternates SHALL share the same shape (all skill, or all sub_track) — they're interchangeable in the DAG.
+- **I11.** Every `Predicate.name` resolves to a known v1 predicate (see §18.4).
+
+### 18.4 Predicate vocabulary (v1)
+
+The closed set of declarative predicates that may appear in Track or Alternate `preconditions[]`:
+
+| Predicate | Argument | Evaluates true when |
+|---|---|---|
+| `requires_git` | — | `git rev-parse --is-inside-work-tree` exits 0 at the project root. |
+| `requires_user_override` | `<value>` | The user explicitly named this alternate in conversation (e.g., "use solo"). |
+| `requires_min_components` | `<int>` | The approved spec has at least N C4 Components. |
+| `requires_phase_completed` | `<phase>` | The named phase appears in `workflow.json → completed`. |
+| `requires_skill_present` | `<skill_id>` | The named skill exists in `EXPECTED_SKILLS ∪ additions.skills`. |
+
+Adding a new predicate is a constitutional change: update this section, update `src/cli/workflows-validator-predicates.js`, and update the corresponding seed.template.md mirror.
+
+### 18.5 `invocation_prompt` / `output_formatter_prompt` — declared, deferred
+
+Both fields are part of the v1 Node schema and validated at parse time. They are **not actuated in v1** — the harness ignores them. They are declared now to lock the schema shape so future Track records can carry them without a schema bump. The v2 actuation plan: Handlebars-style templates with LLM interpolation, allowing per-track UX customization of the invocation phrasing and the post-skill output formatting. Until v2 ships, populating these fields is allowed but inert.
+
+### 18.6 Migration from pre-§18 workflow.json
+
+An in-flight `.claude/state/workflow.json` written by a pre-§18 baseline (carries `entry_phase` field, no `track_id`) is one-shot-migrated by the harness preflight before the workflow loads. The canonical map:
+
+| `entry_phase` (pre-§18) | `track_id` (post-§18) |
+|---|---|
+| `intake` | `intake-full` |
+| `spec` | `spec-entry` |
+| `tdd` | `tdd-quickfix` |
+| `chore` | `chore` |
+
+`completed[]` is remapped from phase names to node ids; the canonical tracks are designed so most phase names equal the corresponding node id (identity remap), with the exception of selector wrappers (e.g., `implementation` in intake-full wraps the swarm-vs-tdd selection). The migrator initializes `skipped_alternates: []` and refreshes `updated_at`. Idempotent: re-running on an already-migrated workflow.json is a no-op. Unmapped `entry_phase` halts with a named error; the user restarts via `/triage`.
+
+Migrator implementation: `src/cli/workflow-migrator.js` exports `migrateWorkflowJsonInPlace(filePath)`.
+
+### 18.7 Lifecycle: install, upgrade, doctor
+
+- **Fresh install.** `scripts/build-template.sh` overlays `src/.claude/workflows.template.jsonl` → `obj/template/.claude/workflows.jsonl` at Stage 2, and the pristine schemas/ directory bulk-rsyncs at Stage 1. The CLI install copies both into the consumer target. Result: every fresh install has `<target>/.claude/workflows.jsonl` with the canonical 4 selectable + 2 sub-track set.
+
+- **Upgrade.** Both `.claude/workflows.jsonl` and `.claude/schemas/workflow-track.v1.json` are `NEVER_TOUCH`. The merge flow returns `NEVER_TOUCH_PRESERVE` for them on every upgrade; user customizations (added tracks, modified nodes, per-project additions like `cli-copy-review`) survive verbatim.
+
+- **Doctor.** `/init-project doctor` (new sub-command) detects drift: missing `workflows.jsonl`, schema/invariant violations, four-way mirror drift between seed.md §18 / src/seed.template.md §18 / CLAUDE.md Article IV / src/CLAUDE.template.md Article IV, and (advisory) shipped-tooling files placed outside `.claude/` per the convention codified at §3.
+
+### 18.8 Cross-references
+
+- `CLAUDE.md Article IV` — phase-ordering rules; binding on every commit-producing track.
+- `CLAUDE.md Article VII` — git rules; relevant to the `requires_git` precondition.
+- `seed.md §3` — directory structure convention (tooling lives under `.claude/`).
+- `seed.md §17` — skill provenance (separate concern; workflows.jsonl is project-owned, not baseline-owned).
+- `.claude/workflows.jsonl` — this project's live tracks.
+- `.claude/schemas/workflow-track.v1.json` — JSON Schema referenced by `Track.$schema`.
+- `src/cli/workflows-validator.js` — validator orchestration.
+- `src/cli/workflows-validator-invariants.js` — invariant checks I1–I11.
+- `src/cli/workflows-validator-predicates.js` — predicate vocabulary.
+- `src/cli/workflow-migrator.js` — pre-§18 → post-§18 migrator.
+- `src/cli/track-tasklist-materializer.js` — Track → TaskList shape.

package/obj/template/.claude/skills/google-analytics/SKILL.md

@@ -1,129 +0,0 @@
----
-name: google-analytics
-description: Comprehensive Google Analytics 4 guide covering property setup, events, custom events, recommended events, custom dimensions, user tracking, audiences, reporting, BigQuery integration, gtag.js implementation, GTM integration, Measurement Protocol, DebugView, privacy compliance, and data management. Use when working with GA4 implementation, tracking, analysis, or any GA4-related tasks.
----
-
-# Google Analytics 4 Complete Guide
-
-## Overview
-
-Google Analytics 4 (GA4) is Google's event-based analytics platform for measuring user interactions across websites and applications. Every user interaction is tracked as an event with associated parameters, providing flexible cross-platform measurement.
-
-## When to Use This Skill
-
-Invoke this skill for any GA4-related task:
-
-- Setting up GA4 properties, data streams, and Measurement IDs
-- Installing GA4 via gtag.js, GTM, or CMS plugins
-- Implementing event tracking (automatic, recommended, custom, ecommerce)
-- Creating custom dimensions, audiences, and reports
-- Exporting data to BigQuery for SQL analysis
-- Server-side tracking via Measurement Protocol
-- User ID and cross-device tracking
-- Privacy compliance, Consent Mode, and GDPR/CCPA
-- Testing and debugging with DebugView
-
-## Quick Start
-
-1. **Create property:** analytics.google.com -> Admin -> Create -> Property
-2. **Create data stream:** Add web stream, note Measurement ID (G-XXXXXXXXXX)
-3. **Install tracking** (choose one):
-   - **GTM (recommended):** Install container, create Google Tag with Measurement ID, trigger on All Pages, publish
-   - **gtag.js direct:**
-     ```html
-     <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
-     <script>
-       window.dataLayer = window.dataLayer || [];
-       function gtag(){dataLayer.push(arguments);}
-       gtag('js', new Date());
-       gtag('config', 'G-XXXXXXXXXX');
-     </script>
-     ```
-4. **Verify:** Enable GA Debugger extension, check Admin -> DebugView for session_start, page_view
-5. **Send custom events:**
-   ```javascript
-   gtag('event', 'button_click', { button_name: 'Subscribe', button_location: 'header' });
-   ```
-
-## Decision Tree: Which Reference Do I Need?
-
-```
-What are you trying to do?
-
-Setting up GA4 for the first time?         -> references/setup.md
-Understanding how events work?              -> references/events-fundamentals.md
-Implementing standard tracking events?      -> references/recommended-events.md
-Creating business-specific custom events?   -> references/custom-events.md
-Making parameters appear in reports?        -> references/custom-dimensions.md
-Implementing User ID / cross-device?        -> references/user-tracking.md
-Building audiences for remarketing?         -> references/audiences.md
-Analysing data in GA4 reports?              -> references/reporting.md
-Exporting to BigQuery for SQL analysis?     -> references/bigquery.md
-Installing via gtag.js directly?            -> references/gtag.md
-Setting up GA4 in Google Tag Manager?       -> references/gtm-integration.md
-Sending events from server/backend?         -> references/measurement-protocol.md
-Testing and debugging implementation?       -> references/debugview.md
-Implementing GDPR/Consent Mode?             -> references/privacy.md
-Configuring Admin settings?                 -> references/data-management.md
-```
-
-## Core Concepts
-
-### Event-Based Model
-
-GA4 tracks everything as events in four categories:
-
-| Category | Description | Examples |
-|----------|-------------|----------|
-| Automatic | Fire without configuration | session_start, first_visit |
-| Enhanced Measurement | Toggle on/off in settings | scroll, click, file_download |
-| Recommended | Google-defined with standard parameters | purchase, login, sign_up |
-| Custom | Business-specific tracking | demo_requested, trial_started |
-
-### Key Limits
-
-| Limit | Value |
-|-------|-------|
-| Event names per property | 500 distinct |
-| Parameters per event | 25 |
-| Event name length | 40 characters |
-| Parameter name/value length | 40 / 100 characters |
-| Custom dimensions (event/user/item) | 50 / 25 / 10 |
-| Audiences per property | 100 |
-
-### Measurement ID
-
-- Format: `G-XXXXXXXXXX` (G- prefix + 10 alphanumeric characters)
-- Location: Admin -> Data Streams -> Web Stream
-- Used in: gtag.js config, GTM tags, Measurement Protocol
-
-## Common Workflows
-
-### Ecommerce Tracking
-
-1. Review [recommended events](references/recommended-events.md) for the purchase funnel: view_item -> add_to_cart -> begin_checkout -> purchase
-2. Structure items array (required: item_id OR item_name; recommended: price, quantity, item_category)
-3. Test with [DebugView](references/debugview.md), then register custom item parameters as [custom dimensions](references/custom-dimensions.md)
-
-### Cross-Device Tracking
-
-1. Implement [User ID](references/user-tracking.md) and configure Reporting Identity (Admin -> Data Settings)
-2. Set [user properties](references/custom-dimensions.md) and build [cross-device audiences](references/audiences.md)
-
-### GDPR Compliance
-
-1. Set up [Consent Mode](references/privacy.md) with default denied state
-2. Integrate with CMP (OneTrust, Cookiebot, etc.), update consent on user acceptance
-3. Test consent implementation with [DebugView](references/debugview.md)
-
-### Custom Reports
-
-1. Understand available data in [reporting](references/reporting.md)
-2. Register custom parameters as [dimensions](references/custom-dimensions.md), create Explorations
-3. For unsampled data, export to [BigQuery](references/bigquery.md)
-
-## Best Practices
-
-- **Naming:** Use snake_case, be descriptive and action-oriented, keep under 40 characters, avoid generic names
-- **Implementation order:** Enhanced Measurement -> recommended events -> custom events -> custom dimensions
-- **Data quality:** Separate test/production properties, set up internal traffic filters from day one, document all custom events, audit regularly with DebugView, export to BigQuery for backup