AGENTS.md

Idea Map Agent Contract

This file contains durable working rules. Read STATE.md before making status claims or changing the project.

Required reading order

1. STATE.md for the current local/live boundary and open gates.
2. docs/01-product-spec.md, docs/10-v2-product-contract.md, docs/11-v2-trust-gate-implementation-plan.md, docs/02-architecture.md, and docs/09-privacy-compliance.md for the implemented V1 baseline, approved V2 direction, executable V2.1 sequence, data, and privacy contracts.
3. docs/03-acceptance.md, docs/05-design-system.md, and the images in mockup/reference/ before changing behavior or visual structure.
4. deploy/README.md and docs/08-cloudflare-release-readiness.md before any operational work. The latter is dated evidence, not automatically current production truth.

Product boundary

Idea Map is a free, self-hosted map of concrete apps, tools, automations, and experiments extracted from public links. The implemented runtime remains the V1/schema-3 core; the local database target additionally contains the non-live V2.1 trust foundation in schema versions 4–7:

• public URL submission;
• bounded source fetch and local AI classification;
• public Live map/feed, Explore, Stats, and interpretation cards;
• correction/removal reporting and public legal pages;
• optional, protected creator/tester connection foundations.

The user approved docs/10-v2-product-contract.md on 2026-08-08 as the next product generation. V2 keeps browsing and public reporting account-free, makes a verified member account mandatory for publishing, separates account verification from creator/project verification, adds structured double-opt-in connections, and permits only clearly labelled contextual Moinsen house promotion with minimal first-party aggregate attribution.

docs/11-v2-trust-gate-implementation-plan.md translates the V2.1 trust gate into an additive migration and release sequence. T1 and the local T2 account/publication slice are implemented and T2 browser acceptance is green; claim proof acquisition, legal release, and production migration are not. Matching, connections, distribution, marketing, and house promotion remain outside the V2.1 implementation boundary.

Do not treat the V2 contract as implemented or live until its acceptance gates pass. Do not add a paid API, remote AI runtime, third-party advertising, behavioral profiling, external analytics, open messaging, payments, fundraising, investment transactions, or a general social feed without another explicit product and privacy decision.

Git and authorization boundary

• This repository now has the user-authorized local develop baseline and an isolated release/schema3-v1 branch, but no configured remote. Do not initialize a remote, push, publish an image, or change live Cloudflare resources outside the explicitly authorized release sequence and the gates recorded in STATE.md.
• Preserve user work and reference assets. Never reset, discard, or overwrite unrelated changes to manufacture a clean tree.
• Local implementation and verification do not prove that production changed. Report local, built, containerized, deployed, and publicly exercised states separately.
• Never print, commit, document, or retain secrets. Production configuration must fail closed when required secrets are absent.

Architecture invariants

• Node.js 22+, React/Vite client, Express API, SQLite, Docker, and local Ollama qwen2.5:3b are the supported baseline.
• Production AI and fetched source text stay on the private server. The model receives bounded text and has no tools, browser, database, or network access.
• SQLite migrations are additive and checksum-tracked. Never edit an applied migration or reuse a version number. Back up before production migration.
• Preserve stable idea IDs, source provenance, and immutable idea revisions so future creator/tester/investor relationships remain backward-compatible.
• Raw IP addresses must not be persisted. Normalize the client network and use the keyed HMAC only for rate limits, abuse defense, and report deduplication.
• Source acquisition must retain protocol, DNS/rebinding, redirect, MIME, response-time, and decoded/raw byte limits. Fixture hosts must never enable a general network bypass, especially in production.
• Production must never seed or render decorative demo ideas.
• In the current runtime, Cloudflare Tunnel protects the public origin, Turnstile protects submission and report forms, and Access applies only to /api/account/*, with JWT validation repeated at the origin. V2 publication authentication must be designed and verified at the origin without making browsing or public rights/illegal-content reporting account-dependent.
• Maintain keyboard access, reduced-motion behavior, mobile layout, and the accepted map-first visual hierarchy.

Data and privacy invariants

• Current local schema target is version 7; the last verified live database is version 2. See STATE.md before making any runtime or migration claim.
• Published idea and revision history must survive retention. Retention may remove failed submissions, expired events/counters, resolved reports, and obsolete pseudonymous client keys according to the documented policy.
• Any new public field, identity link, analytics signal, external provider, or retention change requires a same-release update to docs/09-privacy-compliance.md and the public privacy text.
• V2 account, claim, intent, connection, attribution, consent, moderation, and promotion fields must follow the public/private and retention contracts in docs/10-v2-product-contract.md. Marketing consent must remain separate from account creation, and private contact data must not be revealed before mutual connection acceptance.
• Rights requests must remain actionable after restore. Reapply requests newer than a restored snapshot before reopening public traffic.
• Archive public content first when a credible urgent personal-data or rights complaint arrives; investigate second.

Verification contract

Run the smallest relevant test while iterating, then before handoff run:

npm run check
npm run test:e2e

For container or deployment changes also validate the applicable Compose file. Required variables may use obvious process-local dummy values for syntax-only checks; never write fake production values to an env file.

For AI changes, run the real local-model corpus when Ollama is available:

OLLAMA_URL=http://127.0.0.1:11434 \
OLLAMA_MODEL=qwen2.5:3b \
AI_TIMEOUT_MS=90000 \
npm run ai:eval

Browser work requires an actual browser flow at desktop and mobile widths. Inspect screenshots visually; DOM assertions alone are not visual acceptance. Report intentional skips and warnings rather than hiding them.

For database/backup changes, prove all of the following with disposable data:

• the fresh backup opens and passes SQLite integrity_check;
• its manifest and SHA-256 are present;
• pruning cannot delete the fresh backup or unrelated files;
• published ideas and revisions survive retention and migration.

Operational commands

After npm run build, privacy operations are available through:

npm run privacy -- list-reports
npm run privacy -- archive-idea IDEA_ID
npm run privacy -- resolve-report REPORT_ID resolved
npm run privacy -- find-actor person@example.org
npm run privacy -- delete-actor ACTOR_ID

Treat report details and account email addresses as confidential. Do not paste them into issue trackers, model prompts, screenshots, or handoff documents.

Completion language

A change is complete only when the requested behavior and its relevant data, privacy, migration, responsive, accessibility, and recovery gates pass. State exactly what is:

• implemented locally;
• statically checked or unit-tested;
• exercised in a browser or container;
• deployed;
• publicly verified;
• still a human or operator gate.

Never call a local schema migration, a green build, or a dated evidence file a successful production release.