# C0PY — AGENTS.md

## Canonical mandate

C0PY is the SIAX source of truth for web/product capture, evidence, digital-twin specifications, reconstruction contracts and fidelity verification. Agents MUST follow `docs/MASTERPLAN.md`, `docs/STANDARDS.md`, `docs/AUTOMATIONS.md` and `docs/UPSTREAM-CAPABILITY-MATRIX.md`.

Do not create parallel capture ontologies, alternative evidence schemas or competing fidelity models in this or another SIAX repository.

- **App UUID API**: `wvmn6eg40jofssvm3nigmav6`, server6 — `c0py-api.siax.io`
- **App UUID Web**: `58pa82h4qlzcwsc4shreuwk0`, server6 — `c0py-web.siax.io` (`Dockerfile.web`)
- **Postgres UUID**: `qhucpjjpv3mx9jupqkbyf5uh`, server6
- **Images**: `<app-uuid>:latest` (built on server6 from /tmp/c0py-build)
- **Deploy**: `docker build -t <app-uuid>:latest . && cd /data/coolify/applications/<app-uuid> && docker compose up -d`
- **DNS**: `c0py-api` + `c0py-web` → 65.109.19.146 (Cloudflare A, **DNS-only** — proxied ger TLS-fail på tredjenivå)
- **Coolify API**: POST `/api/v1/applications/dockerfile` (NOT `/api/v1/applications`)
- **Health check**: `GET /health` → 200 (wget-based, Fastify HTTP)
- **⚠️ `c0py.siax.io` apex är Worker-kapad** ("Hello World!") — ej åtgärdbar utan Workers-perms
- **Coolify dockerfile+git-buildpack**: trasig för detta monorepo (build-context saknar repo-träd) — bygg manuellt

## Repo conventions

- Package manager: pnpm (frozen-lockfile)
- Framework: Next.js (`apps/web`), Fastify (`apps/api`)
- TypeScript: strict mode
- Canonical shared contracts: `packages/types`
- Core orchestration: `packages/c0py-core`
- CI: Gitea Actions under `.gitea/workflows/` — `quality` (canonical validator + typecheck + test + build), `security` (trivy, advisory), `contracts` (validator + provenance-policy)
- Deploy: **manuell** per `DEPLOY.md` (Coolify git-buildpack trasig för detta monorepo; CI triggar ej deploy); reconstruction preview adapters may target Vercel
- Secrets: Infisical (`vault.siax.io`), NEVER in repo
- Testing: vitest
- Tenant: bound to trusted session via CL0UD, NEVER client-controlled

## Architecture rules

1. Deterministic measurement beats AI interpretation.
2. Playwright is the canonical browser automation runtime; use CDP for deeper instrumentation.
3. All significant source-product assertions become typed evidence with provenance.
4. Builders (`v0`, `lovable`, `codex`, generic) consume frozen specs and may not redefine source truth.
5. Semantic agents discover candidate workflows; deterministic capture verifies them.
6. Upstream functionality is classified as `CORE`, `DEPENDENCY`, `CHERRY_PICK`, `ADAPTER`, `REIMPLEMENT`, `REFERENCE_ONLY` or `DROP` before integration.
7. Any source-derived code requires repository, commit SHA, source path, license and verification tests.
8. Copyleft/AGPL implementations stay behind isolated adapters/services unless an explicit licensing decision changes this.
9. Clone mode forbids invented facts. Evidence gaps remain explicit.
10. Verification produces a fidelity vector, never a single release score.

- `NEXT_PUBLIC_*` ska ALDRI innehålla hemligheter
- Alla writes till AUD0/ST0RE via klientskikt, aldrig direkt
- Crawling ska vara throttle-ad och respect robots.txt
- **Docker COPY over build stages bryter pnpm-symlinks** — kör `pnpm install --frozen-lockfile` i runtime-staget, lägg till tsx-symlink efteråt
- `tsx` är devDependency i `@siax/c0py-api` — pnpm länkar workspace-devDeps INTE till rot-nivå
- Auth: preHandler hook kollar `Authorization: Bearer *`-header, returnerar 401 annars
- **GitHub push**: använd `gh auth login` (keyring), INTE inbäddade tokens i URLs
- **Coolify compose på disk kan vara stale** — labels/port regenereras ej vid misslyckad deploy; sed:a compose-filen + `docker compose up -d`, och `docker rm -f` gammal container (den lever kvar vid recreate)

## Canonical evidence confidence

Allowed values:

- `measured`
- `observed`
- `inferred`
- `declared`
- `unknown`

Synthetic values are allowed only in adapt/blend mode and must be explicitly marked as synthetic outside source evidence.

## Capture profiles

Authenticated or variant state must be explicit through capture profiles: role, locale, viewport/device, color scheme and feature flags. Never commit credentials, cookies, tokens or storage-state secrets.

## Contract locations

- API: `contracts/openapi.yaml`
- Shared IR/types: `packages/types/src/index.ts`
- Digital Twin Spec: `docs/spec/DIGITAL-TWIN-SPEC.md`
- Canonical Masterplan: `docs/MASTERPLAN.md`
- Engineering/evidence standards: `docs/STANDARDS.md`
- Automation contracts: `docs/AUTOMATIONS.md`
- Upstream adoption: `docs/UPSTREAM-CAPABILITY-MATRIX.md`

## Drift prevention

When a task proposes a new crawler, browser agent, screenshot comparer, product graph, capture schema or clone workflow, first map it onto existing C0PY contracts. Add a new implementation only when it contributes a distinct capability. Remove or reject duplicate sources of truth.

## Security

- Only capture targets/states the operator is authorized to access.
- Never bypass access controls.
- An authorization failure is evidence, not a prompt to evade the boundary.
- `NEXT_PUBLIC_*` must never contain secrets.
- Writes to platform services use their client/integration layers.
- Docker COPY across build stages can break pnpm symlinks; preserve the existing runtime-stage workaround unless replaced and verified.