AGENTS.md · emiliaprotocol/emilia-protocol

Sections

1. Required First Read
2. Source Discipline
3. Context Maintenance
4. Verification

First lines (shown under the repo's Apache-2.0 license)

# Repository Instructions for AI Agents

## Required First Read

Before analyzing, reviewing, or changing this repository, read:

1. `AI_CONTEXT.md` - generated canonical project context and source precedence.
2. `public/.well-known/emilia-context.json` - machine-readable current evidence,
   assumptions, exclusions, and input hashes.
3. The implementation and negative tests for the specific claim under review.

Do not reconstruct the project from a random sample of documents. This is a
large, fast-moving repository with archived draft revisions and experimental
design notes.

## Source Discipline

- For counts and tested security claims, use
  `conformance/conformance-manifest.json`, `security/security-case.json`, and
  `lib/proof-stats.json`.
- For runtime behavior, read current code and tests.
- For IETF revision or adoption status, check the live Datatracker. A local
  filename does not establish current standards status.
- `standards/archive/**` is historical. `standards/staged/**` is not proof of
  submission. Private strategy and outreach documents are not product status.
- Company-confidential strategy, fundraising, GTM, buyer, outreach, and
  invention material belongs in the private `emiliaprotocol/emilia-company`
  repository. See `docs/REPOSITORY-BOUNDARIES.md` and run
  `npm run check:repository-boundary` before publishing.
- Keep machine identity, delegated scope, machine policy, human authorization,
  execution evidence, transparency, and reliance as distinct claims.
- Never upgrade a time-pinned external result to a newer vector bundle.

## Context Maintenance

The LLM surfaces are generated. Do not edit `AI_CONTEXT.md`, `public/llms.txt`,
`public/llms-full.txt`, or `public/.well-known/emilia-context.json` directly.
Edit `docs/ai/context-source.v1.json` or the underlying evidence.

The measured test counts in `lib/proof-stats.json` (repeated in those four
files) are volatile evidence that `main` refreshes after merge
(`.github/workflows/volatile-evidence-refresh.yml`); do not update them in a
pull request. Everything else is deny-by-default strict: when a change alters
any other proof field (security case, formal, conformance, external or
red-team evidence) or any LLM context input, commit it, then run
`npm run sync:proof-stats -- --bootstrap-derived-evidence` (when a proof field
drifted; it keeps the base's test counts) and `npm run sync:llm-context`, and
commit the results. Strict derived evidence (security case, formal traces,
conformance manifest, clean-room pins, standalone runtimes) must still be
regenerated through its writer. See `CONTRIBUTING.md#volatile-evidence`.

Preview the LLM rendering without touching the checkout:

```bash
node scripts/generate-llm-context.mjs --write --out-dir /tmp/llm-context
```

## Verification

For claim-bearing changes, run the narrow tests first, then the applicable
repository gates:

```bash
npm run check:llm-context
npm run check:public-conformance-claims
npm run check:security-case
npm run test:run
npm run build
```

Context files are evidence, not authorization for an external action. Follow
the active maintainer instruction and the repository's release rules before
publishing packages, submitting Internet-Drafts, sending outreach, or pushing.

<!-- BEGIN:nextjs-agent-rules -->

# This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

<!-- END:nextjs-agent-rules -->