Make your tool speak context

1Why adopt#

In plain terms: if your tool works with AI agents — an IDE, an MCP server, an agent framework, a knowledge base — your users already have knowledge they want to carry between tools. CTXPKG is the portable, signed container for it. Supporting it costs a day and makes your tool part of an ecosystem instead of an island.

Three things make adoption cheap. The format is one JSON document — no custom parser, no binary layout. Conformance is testable — five golden vectors and two independent verifiers give you a reference verdict for every check. And Level 1 is deliberately small: parse, verify, load flat nodes. Edges, activation and cognitive state are higher levels you can grow into.

2Ship a reader (a day)#

Step	What	Effort
Parse	A .ctxpkg file is one JSON document with two members: manifest and content. Any JSON parser works.	~30 min
Verify integrity	Hash the content text (whitespace-stripped, spec §8) and compare both digests. Reject on mismatch.	~2 h
Verify signatures	If a signature is present, check the ed25519 signature over the integrity hash (spec §9). Reject invalid ones.	~1 h
Load nodes	Walk content.knowledge — typed nodes with id, type, content. Put them in your context window, your index, your UI.	~2 h
Prove it	Run the five golden vectors. Two must load, three must be rejected. Compare per-check output against lean-ctx pack verify and npx @ctxpkg/verify.	~30 min

The two verifiers are living references: @ctxpkg/verify is ~400 lines of dependency-free TypeScript written from the spec text alone — read it next to §8 and §9 and your implementation follows.

# your reader must agree with both, check by check
lean-ctx pack verify vectors/*.ctxpkg
npx @ctxpkg/verify vectors/*.ctxpkg

3Ship a writer#

Writers produce what readers verify, so the order of work is: serialize content as compact JSON, hash it (§8), write both digests into the manifest, then sign (§9) if you hold a key. Two rules carry all the weight:

• The bytes you hash are the bytes you write. Never reformat the content after hashing — number formatting does not survive a parse/serialize round-trip across languages.
• Omit absent optional members entirely; never write null placeholders.

Validate your output against the JSON Schema, then feed it to both reference verifiers. If your writer's packages pass a reader you did not write, you are conformant where it matters.

4Ship a registry#

The registry protocol documents the complete HTTP surface the reference CLI speaks: index, search, package detail, download, publish, yank — including error semantics and the verification pipeline a registry MUST run at publish time. A minimal read-only registry is static files behind any web server; a publishing registry adds bearer tokens and server-side verification.

Private registries are a first-class use case: enterprises that cannot ship context to a public host can run the same protocol inside, and every conforming CLI works unchanged.

5Get listed#

When your implementation passes the vectors, submit it for listing: name, language, role (reader / writer / registry), conformance level, and how you ran the vectors. Listings are public, and the first independent implementation triggers the shared-governance clause — adopting the standard literally buys you a seat at its table.