Guidance for Claude Code and other AI agents working in this repository.
Codex uses AGENTS.md as its concise entrypoint; both tools share
the workflows under .codex/skills/ and .claude/skills/.
pqforge is a pure-Dart, web-safe post-quantum application toolkit. It is the
composition layer built on pqcrypto
(FIPS 203 ML-KEM, FIPS 204 ML-DSA, FIPS 205 SLH-DSA): KEM-DEM envelopes, AES-256-GCM /
ChaCha20-Poly1305 AEAD, X25519/X448/Ed25519/ECDSA-P256 hybrids plus opt-in
ECDSA-P384 and ECDSA-P521, P-256/P-384 ECDH for TLS hybrid groups and P-521
ECDH for HPKE, RFC 9180 HPKE, bounded-memory streaming, multi-recipient
envelopes, Argon2id key custody, named recipes, compose-sign, and a CLI.
pqforge depends on pqcrypto and never reimplements the lattice
primitives. FIPS 205 SLH-DSA is composed into keygen, key custody,
and detached sign/verify (PqSlhDsaAlgorithm, PqSlhDsaPrimitives). Envelope
headers, streaming signatures, and hybrid-sign remain ML-DSA-only.
compose-sign can take one SLH-DSA leg when that key is passed.
PqEcdsaP521 is not the P-521 HPKE share and not a TLS group. See
doc/HYBRID_AUDIT.md and the
pqforge vs pqcrypto
wiki page.
- Pure Dart, no
dart:ffiin the published package. The core (package:pqforge/pqforge.dart) must stay web-safe — runnable on the Dart VM, Flutter, and the web.dart:iocode lives only behindpackage:pqforge/pqforge_io.dart. The single sanctioned FFI exception is the nested,publish_to: nonedev tooltool/openssl_interop/(excluded from the package via.pubignore). - Respect the claim boundary. Never claim "FIPS validated", "CMVP validated", "certified", hard constant-time Dart behavior, or hard memory erasure. Never add RC4 or unauthenticated encryption. AES encrypts; it never signs. See doc/security/CLAIM_BOUNDARY.md.
- Authenticated encryption only, with explicit domain separation / AAD binding on every recipe.
| Path | Contents |
|---|---|
lib/pqforge.dart |
Web-safe core umbrella (single public import) |
lib/pqforge_io.dart |
dart:io streaming/pack entrypoint (re-exports the core) |
lib/src/algorithms/ |
ML-KEM/ML-DSA wrappers, SLH-DSA algorithm ids, FIPS mode, swappable lattice provider |
lib/src/cipher/ |
AEAD engines (PointyCastle + cryptography), cipher suites, secure session |
lib/src/codecs/ |
.pqf envelope and .pqfs streaming envelope codecs |
lib/src/hybrid/ |
Combiner, cryptography extensions, ECDSA P-256/P-384/P-521, NIST ECDH, X448, hybrid signer, composite signer |
lib/src/keys/ |
Key bundles, custody, wrapping |
lib/src/recipes/ |
Domain-separated recipe message framing |
lib/src/services/ |
Facade services: one-shot, async, stream, pack, multi-recipient |
bin/, bin/src/ |
CLI entrypoint and command groups |
doc/ |
Canonical project docs (see doc/INDEX.md) |
wiki/ |
GitHub Wiki source, synced by .github/workflows/sync-wiki.yml |
site/ |
Homepage index.html is generated. Guide pages in site/content/ and site/lib/ are hand-maintained |
tool/visibility/ |
Visibility generator + manifest (single source for AI-discovery files) |
tool/agent/ |
Deterministic link, publication, and verification workflows |
tool/openssl_interop/ |
Dev-only OpenSSL AEAD interop harness (publish_to: none) |
example/ |
Runnable examples exercised in CI |
test/ |
Tests, including the streaming peak-RSS memory gate |
Two kinds of docs exist, and they are edited differently:
-
Hand-maintained:
README.md,CHANGELOG.md, everything underdoc/, and everything underwiki/. Edit directly. Keep claims aligned to code. -
Generated — never hand-edit:
llms.txt,llms-full.txt,identity.json,faq-ai.txt,developer-ai.txt,ai.txt,robots.txt,robots-ai.txt,.github/copilot-instructions.md,.github/instructions/**,.cursor/rules/**,.windsurfrules,site/index.html,site/styles.css,site/sitemap.xml, and thesite/*.txt/site/*.jsondiscovery copies. Hand-maintained site source issite/content/andsite/lib/. Do not replace those pages when regenerating the homepage. Generated files come fromtool/visibility/visibility_manifest.jsonbytool/visibility/generate_visibility.dart. To change them, edit the manifest (or the generator), then regenerate:dart run tool/visibility/generate_visibility.dart dart run tool/visibility/generate_visibility.dart --check
CI (
.github/workflows/ci.yml,visibility.yml) fails if the generated files are out of sync with the manifest.
Repository links in generated files are built from
project.repository_branch in the manifest — keep it main so published links
never point at a feature branch.
For the full, step-by-step documentation procedure (verification protocol,
no-hallucination rules, the regenerate-and-link checklist), use the
pqforge-docs skill.
For implementation and release work, use
pqforge-feature and
pqforge-release. Before any
git push, use pqforge-push.
dart run tool/agent/verify.dart quick
dart run tool/agent/verify.dart full
dart run tool/agent/verify.dart release # clean release checkoutThe OpenSSL interop tool has its own resolution: dart pub get --directory tool/openssl_interop. Branch model: work on a feature branch off main;
main and develop trigger the Pages and Wiki sync workflows.
- Docs map: doc/INDEX.md
- API reference: doc/API.md
- CLI reference: doc/CLI.md
- Performance facts (measured): doc/technical/PERFORMANCE_AUDIT_AND_HYBRID_CLI.md
- Visibility generator: tool/visibility/README.md
- Agent verification runner: tool/agent/verify.dart