# Specifications

> **Docs site:** this folder deploys as-is to Cloudflare Pages (`index.html` is the landing page):
> `npx wrangler pages deploy docs --project-name aivis-edge-docs` — requires a token with
> **Account · Cloudflare Pages · Edit** (the lab ops token deliberately lacks it) and
> `CLOUDFLARE_ACCOUNT_ID`. These docs are internal until the M5 OSS launch: put a
> **Cloudflare Access** policy (Zero Trust → Access → Applications, free ≤ 50 users, email OTP)
> in front of the project before sharing the URL.

Normative documents for the AIVIS Edge Connector. The HTML files are self-contained — open them in a browser (locally or via raw view).

| Document | Contents |
|---|---|
| [`aivis-edge-connector-architecture.html`](aivis-edge-connector-architecture.html) | Architecture overview rev 3 — system diagrams, decisions **D1–D10** with rationale, request walkthrough, delivery modes & handover, invariants **I1–I8** |
| [`aivis-edge-connector-spec.html`](aivis-edge-connector-spec.html) | Full specification rev 2 — requirement IDs **W-\* C-\* P-\* A-\* V-\* S-\* F-\* T-\* O-\***, config contract, zero-trust pipeline, retraction (C-10/V-08), analytics incl. `INJECT=off` mode (A-07), milestones M1–M6, threat model, test plan |

Canonical editable copies are the claude.ai artifacts (same content, private):
architecture `claude.ai/code/artifact/5c6e024c-a73d-4a2e-8dca-5b746bffa77b` · spec `claude.ai/code/artifact/ec6d30a0-e129-4a01-8682-f39beff7e5dd`. The sibling WordPress connector spec: `claude.ai/code/artifact/40cc266c-ef32-47d0-8775-bd47a3a481fa` and its repository [`epoint-digital/aivis-wordpress-connector`](https://github.com/epoint-digital/aivis-wordpress-connector).

## Decision & verify-at-build register

| ID | Question | Status |
|---|---|---|
| Q-1 | Canonical URL form (normalization contract C-01 / V-07) | **Resolved 2026-09-07 (issue #29):** strict-identity doctrine per WP API-8 — API stays exact + trailing-slash variant; worker strips only advertising params and KEEPS content query params (missing block beats wrong block). Normative contract: `worker/src/normalize.ts` header. Spec C-01's "drop remaining query" default is superseded. |
| Q-2 | Cache API entries purgeable via single-file purge on target plans | Spike in issue #12 |
| Q-3 | Purge API rate limits per plan → domain-purge throttle | Spike in issue #12 |
| Q-4 | Production AIVIS hosting / API base | **Resolved:** `app.aivis-os.com` (WP connector #21) — adopt in issue #28 |
| Q-5 | Serve-gate default (`validated` vs `latest`) | Decision inside issue #17 (platform) |
| Q-6 | Signing-key custody (KMS vs isolated env) | Issue #30 — before M5 |
| Q-7 | Human-traffic sampling in events, or bots-only | Decide in issue #19 |
| Q-8 | License · GitHub org · repo name | **Resolved:** Apache-2.0 · `epoint-digital` · `aivis-edge-connector` (2026-09-07) |

Repo visibility: **private** until the M5 OSS-launch issue flips it public (owner decision 2026-09-07; spec O-01's public-from-first-commit is amended accordingly — commit hygiene still applies as if public).

**Decision amendment (owner, 2026-09-07) — deployment rights are always customer-side.** Spec D1/§04's "Mode A: Aivis-operated via customer API token" does NOT apply to customer accounts: customers deploy the packaged connector themselves; AIVIS provides assistance, support, and new versions only. Consequences: the ops CLI is customer-facing tooling shipped with the package (AIVIS uses the same CLI only on AIVIS-owned properties such as the Edge Lab); the fleet repo holds no customer deploy tokens; freshness on customer zones is TTL-based unless the customer grants an optional **purge-only** token (V-03 `purgeEnabled`). Spec §04/§06 prose to be revised at the M5 docs pass; issues #13/#15/#25 carry the operational detail.