re-voice/AGENTS.md

# Agent Notes (InfraFabric Shadow Dossier Generator)

This repo generates **Shadow Dossiers** by applying versioned style bibles (e.g., IF.DAVE) to extracted source documents.

## Current “Dave” baseline

- Latest bible: `style_bibles/IF_DAVE_BIBLE_v2.6.md` (`if://bible/dave/v2.6`)
- Public static copy (HTML-first): https://infrafabric.io/static/hosted/bibles/IF_DAVE_BIBLE_v2.6.html
- Public static copy (raw): https://infrafabric.io/static/hosted/bibles/IF_DAVE_BIBLE_v2.6.md
- v1.8 generator behavior (implemented in `src/revoice/generate.py`):
  - Adds `MIRROR COMPLETENESS: OK|DEGRADED` (and optional hard fail via `REVOICE_QUALITY_GATE=1`)
  - Adds `## Claims Register (source-attributed)` for measurable claims (numbers, %, tiers, retention windows)
  - Defaults Action Pack ON for v1.8 (disable via `REVOICE_NO_ACTION_PACK=1`)
  - Domain-aware Action Pack gates: hardware/identity, sensors/enforcers, detection/analysis, automation/agentic
 - v2.1 dossier hygiene:
   - Adds a stable online source link in the header: `SOURCE DOC (online): https://infrafabric.io/static/source/<sha256>.pdf`
   - Does not emit `if://bible/...` URIs in public dossier output (use `https://infrafabric.io/static/...` receipts instead)
 - v2.2+ week-pack framing:
   - Uses weekday headings (`## Monday`, etc) + `### Company | Report` subtitle for `mon.pdf`…`sun.pdf` inputs
   - Adds a short “Time journalist” intro and a plain-text “Podcast Script” block (diagram narration)
 - v2.6 intro hygiene:
   - Intro includes **one** rotating “editorial aside” blockquote (banked + week-level no-repeat guidance) to reduce template smell in daily episode drops

## Static hosting (critical trap)

Public static mirror is served from `pct 210:/srv/hosted-static/public` at:
- `https://infrafabric.io/static/hosted/…`

There is a sync job that mirrors `https://git.infrafabric.io/danny/hosted.git` into `/srv/hosted-static/public` every ~5 minutes.

**Important:** The sync uses `rsync --delete`, so anything not in the mirrored repo would normally be removed. To keep operator-generated review artifacts stable, the sync script now excludes:
- `bibles/`
- `review/`
- `iftrace.py` (operator-maintained; don’t overwrite via repo sync)
- `verticals/` (currently operator-maintained; don’t overwrite via repo sync)

The IF.TTT public homepage *is* synced from the repo:
- Repo folder: `ifttt/`
- Publish path: `https://infrafabric.io/` and `https://infrafabric.io/static/hosted/ifttt/`

IF.TTT site routes (no login):
- `https://infrafabric.io/about/`
- `https://infrafabric.io/api/`
- `https://infrafabric.io/verticals/`
- `https://infrafabric.io/governance/` (open governance + charter links)
- `https://infrafabric.io/whitepaper/` (IF.TTT paper + optional email request)
- `https://infrafabric.io/fr/` (French stub)

Legacy trap: older PDFs referenced `https://infrafabric.io/static/hosted/gov/README.md`; it now redirects to `https://infrafabric.io/governance/`.

So **publish operator-generated bibles/review packs under**:
- `/srv/hosted-static/public/bibles/…`
- `/srv/hosted-static/public/review/…`

## HTML-only sandbox fallback (new; critical for external reviewers)

Some LLM “web fetchers” can load HTML but fail on `.md/.py/.tar.gz`. To keep the IF.TTT “open governance” premise intact for external review:

- Keep the raw assets (`.md`, `.tar.gz`) **and** provide an **HTML view** on the same stable alias surface.
- Share surface:
  - Raw pack: `/static/pack/<shareId>.md`
  - HTML pack view: `/static/pack/<shareId>`
  - Raw review pack: `/static/review/<shareId>.md` (alt: `/static/review-pack/<shareId>.md`)
  - HTML review pack view: `/static/review/<shareId>` (alt: `/static/review-pack/<shareId>`)
  - Raw marketing: `/static/marketing/<shareId>.md`
  - HTML marketing view: `/static/marketing/<shareId>`
- Hosted review artifacts (`/static/hosted/review/**`) also have `.html` wrappers generated post-sync.

Implementation notes:
- Caddy rewrites `/static/*` (HTML view endpoints) to the red-team app (`pct 212`).
- Hosted `.html` wrappers are generated by `pct 210:/usr/local/bin/hosted_static_build_html_wrappers.py` after each sync.

## Full stack + links (operator reference)

- `/root/docs/19-ifttt-full-stack-and-working-links.md` is the “single page” reference for:
  - Which apps run where (pct IDs + IPs)
  - Which URLs are canonical for sharing
  - Copy/paste-safe example links
- IF.TTT public overview page (hosted-static): https://infrafabric.io/static/hosted/ifttt/

## IF.TRACE paper update review pack (known-good example)

Use this pack when requesting external critique of the IF.TRACE paper update (receipt-first chronology + public receipts + triage bundles):

- Pack (HTML): `https://infrafabric.io/static/hosted/review/iftrace-paper-update/2025-12-29/review-pack.html`
- Pack (MD): `https://infrafabric.io/static/hosted/review/iftrace-paper-update/2025-12-29/review-pack.md`
- Pack hash: `https://infrafabric.io/static/hosted/review/iftrace-paper-update/2025-12-29/review-pack.tar.gz.sha256`
- Triage selector demo (canonical): `https://infrafabric.io/static/hosted/review/trace-bundles/b6547c03/index.md`
- Offline verifier: `https://infrafabric.io/static/hosted/iftrace.py`

Note: some LLM “web fetchers” reject `.tar.gz` with a client-side `415` even when browsers/curl succeed; use the `.html` pack in those environments.

## IF.TTT homepage redesign review pack (HTML-first; single link)

Use this when asking external reviewers (including other LLMs) to critique the `infrafabric.io/` homepage redesign spec (OK Computer minimalism + “black/white” verification messaging):

- Landing: `https://infrafabric.io/static/hosted/review/ifttt-homepage-redesign/2025-12-29/`
- Pack (HTML): `https://infrafabric.io/static/hosted/review/ifttt-homepage-redesign/2025-12-29/review-pack.html`
- Pack (MD): `https://infrafabric.io/static/hosted/review/ifttt-homepage-redesign/2025-12-29/review-pack.md`

## Week review packs (v1.8)

Week v1.8 packs are published here:
- Index: `https://infrafabric.io/static/hosted/review/week-v1.8/2025-12-27/index.md`
- Full single-file bundle: `https://infrafabric.io/static/hosted/review/week-v1.8/2025-12-27/week.pack.md`

Each day also has:
- `/<day>.pack.md` (offline-friendly; embeds source + dossier + trace + marketing thread)
- `/<day>.shadow.md`
- `/<day>.trace.json`
- `/<day>.marketing.md`

## Week review packs (v1.9)

Week v1.9 packs are published here:
- Index: `https://infrafabric.io/static/hosted/review/week-v1.9/2025-12-28/index.md`
- Full single-file bundle: `https://infrafabric.io/static/hosted/review/week-v1.9/2025-12-28/week.pack.md`

## Week pack generator (local)

To regenerate a week bundle locally (and then publish to hosted-static), use:
- `re-voice/tools/week_pack/build_week.py`

## OpSec / sharing rules

- Do not leak internal hostnames, paths, container IDs, or pipeline errors into outputs.
- For external reviewers, prefer **static** review packs (`/static/hosted/review/...`) or red-team app bundles (`/static/pack/<id>.md`).
- Avoid deep-linking Forgejo for public review; use `infrafabric.io/static/...` mirrors instead.