codama-idl · lorisleiva · Aug 31, 2026 · Aug 31, 2026
diff --git a/.changeset/one-major-per-line-layout.md b/.changeset/one-major-per-line-layout.md
@@ -0,0 +1,5 @@
+---
+'@codama/spec': major
+---
+
+Restructure the package for the one-major-per-line release model: the root entrypoint now hosts the current major's spec surface from `src/spec/` (formerly `src/v1/`), the `./v1` subpath export is removed (the v1 spec remains available as `@codama/spec@^1` from the `1.x` line), and the generated artifacts move from `v1/` to the repository root (`spec.json`, `schema.json`, `docs/`). The generated docs landing page now links to the docs of previous majors on their maintenance branches.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -21,10 +21,10 @@ pnpm test
 
 See the [README](./README.md) for a top-level tour. The short version:
 
-- `src/` — package source (the `@codama/spec` public surface, including the meta-model API and the latest-major spec data).
+- `src/` — package source (the `@codama/spec` public surface: the meta-model API under `src/api/` and this line's spec content under `src/spec/`).
 - `tests/` — package tests.
-- `generators/` — internal codegen orchestrator and per-target generators. Not exported from the package; produces the `v<n>/` artifacts.
-- `v1/` — generated artifacts mirroring the `@codama/spec/v1` surface (`spec.json`, `schema.json`, `docs/`). Treat as machine output; edit the spec or the generators, not these files.
+- `generators/` — internal codegen orchestrator and per-target generators. Not exported from the package; produces the generated artifacts.
+- `spec.json`, `schema.json`, `docs/` — generated artifacts mirroring the `@codama/spec` surface. Treat as machine output; edit the spec or the generators, not these files.
 - `.changeset/` — release intent files managed by [`@changesets/cli`](https://github.com/changesets/changesets).
 
 ## Making changes
@@ -106,10 +106,10 @@ train).
 
 The package version in `package.json` is the single source of truth, bumped by
 changesets at release time. The spec version (`SPEC_VERSION` in
-`src/v1/version.ts`, embedded in `v1/spec.json` and the generated docs) always
+`src/spec/version.ts`, embedded in `spec.json` and the generated docs) always
 mirrors it: the Release package PR runs `pnpm release:version`, which calls
-`changeset version`, syncs `src/v1/version.ts` via
-`scripts/sync-spec-version.ts`, and regenerates the `v1/` artifacts — all in
+`changeset version`, syncs `src/spec/version.ts` via
+`scripts/sync-spec-version.ts`, and regenerates the artifacts — all in
 the same commit. Never edit `SPEC_VERSION` by hand; a unit test fails if it
 drifts from the package version.
 
@@ -120,8 +120,9 @@ drifts from the package version.
   [`@solana-config/oxc`](https://www.npmjs.com/package/@solana-config/oxc) as
   the shared base. `pnpm lint` runs both (with type-aware rules enabled);
   `pnpm lint:fix` applies their autofixes.
-- Generated files under `v1/` are committed but treated as machine output —
-  edit the spec or the generators, not the generated files.
+- Generated files (`spec.json`, `schema.json`, `docs/`) are committed but
+  treated as machine output — edit the spec or the generators, not the
+  generated files.
 
 ## Reporting issues
 

diff --git a/README.md b/README.md
@@ -6,9 +6,11 @@ The canonical Codama node specification.
 
 Codama is a standard for describing on-chain Solana programs as a graph of typed nodes (accounts, instructions, types, …). This repository contains:
 
-- **The spec.** A machine-readable description of every node in the Codama node graph, authored in TypeScript under `src/` and emitted as `v1/spec.json`. Future Codama majors will land alongside as `v2/spec.json`, `v3/spec.json`, …
+- **The spec.** A machine-readable description of every node in the Codama node graph, authored in TypeScript under `src/spec/` and emitted as `spec.json`.
 - **The meta-model API.** Authoring helpers (`defineNode`, `attribute`, primitives, compounds, …) exposed at `@codama/spec/api` for hand-authoring specs and test fixtures.
-- **Internal codegen.** Generators under `generators/` produce the public artifacts that mirror each spec major (`v<n>/spec.json`, `v<n>/schema.json`, `v<n>/docs/`). They are not exported from the `@codama/spec` package; they exist as internal tooling for this repo.
+- **Internal codegen.** Generators under `generators/` produce the public artifacts (`spec.json`, `schema.json`, `docs/`). They are not exported from the `@codama/spec` package; they exist as internal tooling for this repo.
+
+Each release line hosts exactly one spec major: this branch carries the current major, and previous majors live on their own maintenance branches (e.g. [`1.x`](https://github.com/codama-idl/spec/tree/1.x)) and publish as their own npm versions (e.g. `@codama/spec@^1`). See [RELEASING.md](./RELEASING.md).
 
 Reference implementations (TypeScript node types, node factories, visitors, validators, renderers, the CLI) live in [codama-idl/codama](https://github.com/codama-idl/codama) and consume the published `@codama/spec` package. The Rust reference implementation lives in [codama-idl/codama-rs](https://github.com/codama-idl/codama-rs).
 
@@ -21,20 +23,19 @@ pnpm add @codama/spec
 
 ## Quickstart
 
-`@codama/spec` exposes three entrypoints:
+`@codama/spec` exposes two entrypoints:
 
-- `@codama/spec` — the latest stable major's public surface. Re-exports `@codama/spec/v1` today; will track future majors.
-- `@codama/spec/v1` — the v1 spec data, accessors (`getSpec`, `getNode`, `getUnion`, `getEnumeration`), and the version-agnostic types (`NodeSpec`, `UnionSpec`, …).
+- `@codama/spec` — the spec data of this release line's major: accessors (`getSpec`, `getNode`, `getUnion`, `getEnumeration`), the `SPEC_VERSION` constant, and the version-agnostic types (`NodeSpec`, `UnionSpec`, …).
 - `@codama/spec/api` — the meta-model authoring API (`defineNode`, `attribute`, primitives, compounds, …) for hand-authoring specs and test fixtures.
 
 ### Read the spec
 
 ```ts
-import { getSpec, getNode, SPEC_VERSION } from '@codama/spec/v1';
+import { getSpec, getNode, SPEC_VERSION } from '@codama/spec';
 
 const spec = getSpec();
-console.log(spec.version); // → '1.8.0'
-console.log(SPEC_VERSION); // → '1.8.0'
+console.log(spec.version); // → '2.0.0'
+console.log(SPEC_VERSION); // → '2.0.0'
 
 const account = getNode('accountNode');
 console.log(account?.attributes.map(a => a.name));
@@ -78,16 +79,17 @@ Preserving declaration order keeps encoded IDLs readable: the identifying scalar
 
 ```
 src/                       # package source (the @codama/spec public surface)
+  api/                     # the meta-model authoring API (@codama/spec/api)
+  spec/                    # the current major's spec content (re-exported by the root)
 tests/                     # package tests
 generators/                # internal codegen orchestrator + per-target generators
   index.ts                 # runs every registered generator sequentially
-  json-spec/               # emits v<n>/spec.json
-  json-schema/             # emits v<n>/schema.json (stub)
-  docs/                    # renders the spec as markdown and emits v<n>/docs/
-v1/                        # generated artifacts mirroring the @codama/spec/v1 surface
-  spec.json
-  schema.json
-  docs/
+  json-spec/               # emits spec.json
+  json-schema/             # emits schema.json (stub)
+  docs/                    # renders the spec as markdown and emits docs/
+spec.json                  # generated: the encoded spec
+schema.json                # generated: JSON Schema (stub)
+docs/                      # generated: browsable markdown docs
 .changeset/                # release intent files (managed by @changesets/cli)
 ```
 

diff --git a/v1/docs/AccountNode.md → docs/AccountNode.md b/v1/docs/AccountNode.md → docs/AccountNode.md
diff --git a/v1/docs/ConstantNode.md → docs/ConstantNode.md b/v1/docs/ConstantNode.md → docs/ConstantNode.md
diff --git a/v1/docs/DefinedTypeNode.md → docs/DefinedTypeNode.md b/v1/docs/DefinedTypeNode.md → docs/DefinedTypeNode.md
diff --git a/v1/docs/ErrorNode.md → docs/ErrorNode.md b/v1/docs/ErrorNode.md → docs/ErrorNode.md
diff --git a/v1/docs/EventNode.md → docs/EventNode.md b/v1/docs/EventNode.md → docs/EventNode.md
diff --git a/v1/docs/InstructionAccountNode.md → docs/InstructionAccountNode.md b/v1/docs/InstructionAccountNode.md → docs/InstructionAccountNode.md
diff --git a/v1/docs/InstructionArgumentNode.md → docs/InstructionArgumentNode.md b/v1/docs/InstructionArgumentNode.md → docs/InstructionArgumentNode.md
diff --git a/v1/docs/InstructionByteDeltaNode.md → docs/InstructionByteDeltaNode.md b/v1/docs/InstructionByteDeltaNode.md → docs/InstructionByteDeltaNode.md
diff --git a/v1/docs/InstructionByteDeltaValue.md → docs/InstructionByteDeltaValue.md b/v1/docs/InstructionByteDeltaValue.md → docs/InstructionByteDeltaValue.md
diff --git a/v1/docs/InstructionNode.md → docs/InstructionNode.md b/v1/docs/InstructionNode.md → docs/InstructionNode.md
diff --git a/v1/docs/InstructionRemainingAccountsNode.md → docs/InstructionRemainingAccountsNode.md b/v1/docs/InstructionRemainingAccountsNode.md → docs/InstructionRemainingAccountsNode.md
diff --git a/v1/docs/InstructionRemainingAccountsValue.md → docs/InstructionRemainingAccountsValue.md b/v1/docs/InstructionRemainingAccountsValue.md → docs/InstructionRemainingAccountsValue.md
diff --git a/v1/docs/InstructionStatusNode.md → docs/InstructionStatusNode.md b/v1/docs/InstructionStatusNode.md → docs/InstructionStatusNode.md
diff --git a/v1/docs/PdaNode.md → docs/PdaNode.md b/v1/docs/PdaNode.md → docs/PdaNode.md
diff --git a/v1/docs/PluginNode.md → docs/PluginNode.md b/v1/docs/PluginNode.md → docs/PluginNode.md
diff --git a/v1/docs/ProgramNode.md → docs/ProgramNode.md b/v1/docs/ProgramNode.md → docs/ProgramNode.md
diff --git a/v1/docs/ProvidedNode.md → docs/ProvidedNode.md b/v1/docs/ProvidedNode.md → docs/ProvidedNode.md
diff --git a/v1/docs/README.md → docs/README.md b/v1/docs/README.md → docs/README.md
@@ -2,7 +2,7 @@
 
 The canonical Codama node specification.
 
-Spec version: 1.9.2
+Spec version: 1.9.2 · Other majors: [v1](https://github.com/codama-idl/spec/blob/1.x/v1/docs/README.md)
 
 Pages marked _(abstract)_ document unions: sets of nodes that can be used interchangeably. Pages marked _(recursive)_ document nested unions: wrapper nodes that may nest before reaching a base type.
 

diff --git a/v1/docs/RootNode.md → docs/RootNode.md b/v1/docs/RootNode.md → docs/RootNode.md
diff --git a/...textualValueNodes/AccountBumpValueNode.md → ...textualValueNodes/AccountBumpValueNode.md b/...textualValueNodes/AccountBumpValueNode.md → ...textualValueNodes/AccountBumpValueNode.md
diff --git a/...extualValueNodes/AccountFieldValueNode.md → ...extualValueNodes/AccountFieldValueNode.md b/...extualValueNodes/AccountFieldValueNode.md → ...extualValueNodes/AccountFieldValueNode.md
diff --git a/.../contextualValueNodes/AccountValueNode.md → .../contextualValueNodes/AccountValueNode.md b/.../contextualValueNodes/AccountValueNode.md → .../contextualValueNodes/AccountValueNode.md
diff --git a/...contextualValueNodes/ArgumentValueNode.md → ...contextualValueNodes/ArgumentValueNode.md b/...contextualValueNodes/ArgumentValueNode.md → ...contextualValueNodes/ArgumentValueNode.md
diff --git a/...alValueNodes/ConditionalValueCondition.md → ...alValueNodes/ConditionalValueCondition.md b/...alValueNodes/ConditionalValueCondition.md → ...alValueNodes/ConditionalValueCondition.md
diff --git a/...textualValueNodes/ConditionalValueNode.md → ...textualValueNodes/ConditionalValueNode.md b/...textualValueNodes/ConditionalValueNode.md → ...textualValueNodes/ConditionalValueNode.md
diff --git a/...ntextualValueNodes/ContextualValueNode.md → ...ntextualValueNodes/ContextualValueNode.md b/...ntextualValueNodes/ContextualValueNode.md → ...ntextualValueNodes/ContextualValueNode.md
diff --git a/...contextualValueNodes/IdentityValueNode.md → ...contextualValueNodes/IdentityValueNode.md b/...contextualValueNodes/IdentityValueNode.md → ...contextualValueNodes/IdentityValueNode.md
diff --git a/...alValueNodes/InstructionInputValueNode.md → ...alValueNodes/InstructionInputValueNode.md b/...alValueNodes/InstructionInputValueNode.md → ...alValueNodes/InstructionInputValueNode.md
diff --git a/...cs/contextualValueNodes/PayerValueNode.md → docs/contextualValueNodes/PayerValueNode.md b/...cs/contextualValueNodes/PayerValueNode.md → docs/contextualValueNodes/PayerValueNode.md
diff --git a/.../contextualValueNodes/PdaSeedValueNode.md → .../contextualValueNodes/PdaSeedValueNode.md b/.../contextualValueNodes/PdaSeedValueNode.md → .../contextualValueNodes/PdaSeedValueNode.md
diff --git a/...contextualValueNodes/PdaSeedValueValue.md → ...contextualValueNodes/PdaSeedValueValue.md b/...contextualValueNodes/PdaSeedValueValue.md → ...contextualValueNodes/PdaSeedValueValue.md
diff --git a/v1/docs/contextualValueNodes/PdaValueNode.md → docs/contextualValueNodes/PdaValueNode.md b/v1/docs/contextualValueNodes/PdaValueNode.md → docs/contextualValueNodes/PdaValueNode.md
diff --git a/v1/docs/contextualValueNodes/PdaValuePda.md → docs/contextualValueNodes/PdaValuePda.md b/v1/docs/contextualValueNodes/PdaValuePda.md → docs/contextualValueNodes/PdaValuePda.md
diff --git a/...contextualValueNodes/PdaValueProgramId.md → ...contextualValueNodes/PdaValueProgramId.md b/...contextualValueNodes/PdaValueProgramId.md → ...contextualValueNodes/PdaValueProgramId.md
diff --git a/...ontextualValueNodes/ProgramIdValueNode.md → ...ontextualValueNodes/ProgramIdValueNode.md b/...ontextualValueNodes/ProgramIdValueNode.md → ...ontextualValueNodes/ProgramIdValueNode.md
diff --git a/v1/docs/contextualValueNodes/README.md → docs/contextualValueNodes/README.md b/v1/docs/contextualValueNodes/README.md → docs/contextualValueNodes/README.md
diff --git a/...lueNodes/RegisteredContextualValueNode.md → ...lueNodes/RegisteredContextualValueNode.md b/...lueNodes/RegisteredContextualValueNode.md → ...lueNodes/RegisteredContextualValueNode.md
diff --git a/...ontextualValueNodes/ResolverDependency.md → ...ontextualValueNodes/ResolverDependency.md b/...ontextualValueNodes/ResolverDependency.md → ...ontextualValueNodes/ResolverDependency.md
diff --git a/...contextualValueNodes/ResolverValueNode.md → ...contextualValueNodes/ResolverValueNode.md b/...contextualValueNodes/ResolverValueNode.md → ...contextualValueNodes/ResolverValueNode.md
diff --git a/...lueNodes/StandaloneContextualValueNode.md → ...lueNodes/StandaloneContextualValueNode.md b/...lueNodes/StandaloneContextualValueNode.md → ...lueNodes/StandaloneContextualValueNode.md
diff --git a/v1/docs/countNodes/CountNode.md → docs/countNodes/CountNode.md b/v1/docs/countNodes/CountNode.md → docs/countNodes/CountNode.md
diff --git a/v1/docs/countNodes/FixedCountNode.md → docs/countNodes/FixedCountNode.md b/v1/docs/countNodes/FixedCountNode.md → docs/countNodes/FixedCountNode.md
diff --git a/v1/docs/countNodes/PrefixedCountNode.md → docs/countNodes/PrefixedCountNode.md b/v1/docs/countNodes/PrefixedCountNode.md → docs/countNodes/PrefixedCountNode.md
diff --git a/v1/docs/countNodes/README.md → docs/countNodes/README.md b/v1/docs/countNodes/README.md → docs/countNodes/README.md
diff --git a/v1/docs/countNodes/RegisteredCountNode.md → docs/countNodes/RegisteredCountNode.md b/v1/docs/countNodes/RegisteredCountNode.md → docs/countNodes/RegisteredCountNode.md
diff --git a/v1/docs/countNodes/RemainderCountNode.md → docs/countNodes/RemainderCountNode.md b/v1/docs/countNodes/RemainderCountNode.md → docs/countNodes/RemainderCountNode.md
diff --git a/...minatorNodes/ConstantDiscriminatorNode.md → ...minatorNodes/ConstantDiscriminatorNode.md b/...minatorNodes/ConstantDiscriminatorNode.md → ...minatorNodes/ConstantDiscriminatorNode.md
diff --git a/...s/discriminatorNodes/DiscriminatorNode.md → docs/discriminatorNodes/DiscriminatorNode.md b/...s/discriminatorNodes/DiscriminatorNode.md → docs/discriminatorNodes/DiscriminatorNode.md
diff --git a/...criminatorNodes/FieldDiscriminatorNode.md → ...criminatorNodes/FieldDiscriminatorNode.md b/...criminatorNodes/FieldDiscriminatorNode.md → ...criminatorNodes/FieldDiscriminatorNode.md
diff --git a/v1/docs/discriminatorNodes/README.md → docs/discriminatorNodes/README.md b/v1/docs/discriminatorNodes/README.md → docs/discriminatorNodes/README.md
diff --git a/...natorNodes/RegisteredDiscriminatorNode.md → ...natorNodes/RegisteredDiscriminatorNode.md b/...natorNodes/RegisteredDiscriminatorNode.md → ...natorNodes/RegisteredDiscriminatorNode.md
diff --git a/...scriminatorNodes/SizeDiscriminatorNode.md → ...scriminatorNodes/SizeDiscriminatorNode.md b/...scriminatorNodes/SizeDiscriminatorNode.md → ...scriminatorNodes/SizeDiscriminatorNode.md
diff --git a/...s/displayNodes/AmountNumberDisplayNode.md → docs/displayNodes/AmountNumberDisplayNode.md b/...s/displayNodes/AmountNumberDisplayNode.md → docs/displayNodes/AmountNumberDisplayNode.md
diff --git a/...displayNodes/DateTimeNumberDisplayNode.md → ...displayNodes/DateTimeNumberDisplayNode.md b/...displayNodes/DateTimeNumberDisplayNode.md → ...displayNodes/DateTimeNumberDisplayNode.md
diff --git a/v1/docs/displayNodes/DisplayNode.md → docs/displayNodes/DisplayNode.md b/v1/docs/displayNodes/DisplayNode.md → docs/displayNodes/DisplayNode.md
diff --git a/...displayNodes/DurationNumberDisplayNode.md → ...displayNodes/DurationNumberDisplayNode.md b/...displayNodes/DurationNumberDisplayNode.md → ...displayNodes/DurationNumberDisplayNode.md
diff --git a/...cs/displayNodes/EnumVariantDisplayNode.md → docs/displayNodes/EnumVariantDisplayNode.md b/...cs/displayNodes/EnumVariantDisplayNode.md → docs/displayNodes/EnumVariantDisplayNode.md
diff --git a/...layNodes/InstructionAccountDisplayNode.md → ...layNodes/InstructionAccountDisplayNode.md b/...layNodes/InstructionAccountDisplayNode.md → ...layNodes/InstructionAccountDisplayNode.md
diff --git a/...cs/displayNodes/InstructionDisplayNode.md → docs/displayNodes/InstructionDisplayNode.md b/...cs/displayNodes/InstructionDisplayNode.md → docs/displayNodes/InstructionDisplayNode.md
diff --git a/v1/docs/displayNodes/NumberDisplayNode.md → docs/displayNodes/NumberDisplayNode.md b/v1/docs/displayNodes/NumberDisplayNode.md → docs/displayNodes/NumberDisplayNode.md
diff --git a/v1/docs/displayNodes/README.md → docs/displayNodes/README.md b/v1/docs/displayNodes/README.md → docs/displayNodes/README.md
diff --git a/...ocs/displayNodes/RegisteredDisplayNode.md → docs/displayNodes/RegisteredDisplayNode.md b/...ocs/displayNodes/RegisteredDisplayNode.md → docs/displayNodes/RegisteredDisplayNode.md
diff --git a/v1/docs/displayNodes/StringDisplayNode.md → docs/displayNodes/StringDisplayNode.md b/v1/docs/displayNodes/StringDisplayNode.md → docs/displayNodes/StringDisplayNode.md
diff --git a/...cs/displayNodes/StructFieldDisplayNode.md → docs/displayNodes/StructFieldDisplayNode.md b/...cs/displayNodes/StructFieldDisplayNode.md → docs/displayNodes/StructFieldDisplayNode.md
diff --git a/v1/docs/linkNodes/AccountLinkNode.md → docs/linkNodes/AccountLinkNode.md b/v1/docs/linkNodes/AccountLinkNode.md → docs/linkNodes/AccountLinkNode.md
diff --git a/v1/docs/linkNodes/DefinedTypeLinkNode.md → docs/linkNodes/DefinedTypeLinkNode.md b/v1/docs/linkNodes/DefinedTypeLinkNode.md → docs/linkNodes/DefinedTypeLinkNode.md
diff --git a/...s/linkNodes/InstructionAccountLinkNode.md → docs/linkNodes/InstructionAccountLinkNode.md b/...s/linkNodes/InstructionAccountLinkNode.md → docs/linkNodes/InstructionAccountLinkNode.md
diff --git a/.../linkNodes/InstructionArgumentLinkNode.md → .../linkNodes/InstructionArgumentLinkNode.md b/.../linkNodes/InstructionArgumentLinkNode.md → .../linkNodes/InstructionArgumentLinkNode.md
diff --git a/v1/docs/linkNodes/InstructionLinkNode.md → docs/linkNodes/InstructionLinkNode.md b/v1/docs/linkNodes/InstructionLinkNode.md → docs/linkNodes/InstructionLinkNode.md
diff --git a/v1/docs/linkNodes/LinkNode.md → docs/linkNodes/LinkNode.md b/v1/docs/linkNodes/LinkNode.md → docs/linkNodes/LinkNode.md
diff --git a/v1/docs/linkNodes/PdaLinkNode.md → docs/linkNodes/PdaLinkNode.md b/v1/docs/linkNodes/PdaLinkNode.md → docs/linkNodes/PdaLinkNode.md
diff --git a/v1/docs/linkNodes/ProgramLinkNode.md → docs/linkNodes/ProgramLinkNode.md b/v1/docs/linkNodes/ProgramLinkNode.md → docs/linkNodes/ProgramLinkNode.md
diff --git a/v1/docs/linkNodes/README.md → docs/linkNodes/README.md b/v1/docs/linkNodes/README.md → docs/linkNodes/README.md
diff --git a/v1/docs/linkNodes/RegisteredLinkNode.md → docs/linkNodes/RegisteredLinkNode.md b/v1/docs/linkNodes/RegisteredLinkNode.md → docs/linkNodes/RegisteredLinkNode.md
diff --git a/v1/docs/pdaSeedNodes/ConstantPdaSeedNode.md → docs/pdaSeedNodes/ConstantPdaSeedNode.md b/v1/docs/pdaSeedNodes/ConstantPdaSeedNode.md → docs/pdaSeedNodes/ConstantPdaSeedNode.md
diff --git a/v1/docs/pdaSeedNodes/ConstantPdaSeedValue.md → docs/pdaSeedNodes/ConstantPdaSeedValue.md b/v1/docs/pdaSeedNodes/ConstantPdaSeedValue.md → docs/pdaSeedNodes/ConstantPdaSeedValue.md
diff --git a/v1/docs/pdaSeedNodes/PdaSeedNode.md → docs/pdaSeedNodes/PdaSeedNode.md b/v1/docs/pdaSeedNodes/PdaSeedNode.md → docs/pdaSeedNodes/PdaSeedNode.md
diff --git a/v1/docs/pdaSeedNodes/README.md → docs/pdaSeedNodes/README.md b/v1/docs/pdaSeedNodes/README.md → docs/pdaSeedNodes/README.md
diff --git a/...ocs/pdaSeedNodes/RegisteredPdaSeedNode.md → docs/pdaSeedNodes/RegisteredPdaSeedNode.md b/...ocs/pdaSeedNodes/RegisteredPdaSeedNode.md → docs/pdaSeedNodes/RegisteredPdaSeedNode.md
diff --git a/v1/docs/pdaSeedNodes/VariablePdaSeedNode.md → docs/pdaSeedNodes/VariablePdaSeedNode.md b/v1/docs/pdaSeedNodes/VariablePdaSeedNode.md → docs/pdaSeedNodes/VariablePdaSeedNode.md
diff --git a/v1/docs/sharedNodes/BytesEncoding.md → docs/sharedNodes/BytesEncoding.md b/v1/docs/sharedNodes/BytesEncoding.md → docs/sharedNodes/BytesEncoding.md
diff --git a/v1/docs/sharedNodes/DefaultValueStrategy.md → docs/sharedNodes/DefaultValueStrategy.md b/v1/docs/sharedNodes/DefaultValueStrategy.md → docs/sharedNodes/DefaultValueStrategy.md
diff --git a/v1/docs/sharedNodes/DisplaySkip.md → docs/sharedNodes/DisplaySkip.md b/v1/docs/sharedNodes/DisplaySkip.md → docs/sharedNodes/DisplaySkip.md
diff --git a/v1/docs/sharedNodes/Endianness.md → docs/sharedNodes/Endianness.md b/v1/docs/sharedNodes/Endianness.md → docs/sharedNodes/Endianness.md
diff --git a/v1/docs/sharedNodes/InstructionLifecycle.md → docs/sharedNodes/InstructionLifecycle.md b/v1/docs/sharedNodes/InstructionLifecycle.md → docs/sharedNodes/InstructionLifecycle.md
diff --git a/v1/docs/sharedNodes/NumberFormat.md → docs/sharedNodes/NumberFormat.md b/v1/docs/sharedNodes/NumberFormat.md → docs/sharedNodes/NumberFormat.md
diff --git a/...cs/sharedNodes/OptionalAccountStrategy.md → docs/sharedNodes/OptionalAccountStrategy.md b/...cs/sharedNodes/OptionalAccountStrategy.md → docs/sharedNodes/OptionalAccountStrategy.md
diff --git a/v1/docs/sharedNodes/PostOffsetStrategy.md → docs/sharedNodes/PostOffsetStrategy.md b/v1/docs/sharedNodes/PostOffsetStrategy.md → docs/sharedNodes/PostOffsetStrategy.md
diff --git a/v1/docs/sharedNodes/PreOffsetStrategy.md → docs/sharedNodes/PreOffsetStrategy.md b/v1/docs/sharedNodes/PreOffsetStrategy.md → docs/sharedNodes/PreOffsetStrategy.md
diff --git a/v1/docs/sharedNodes/ProgramOrigin.md → docs/sharedNodes/ProgramOrigin.md b/v1/docs/sharedNodes/ProgramOrigin.md → docs/sharedNodes/ProgramOrigin.md
diff --git a/v1/docs/sharedNodes/README.md → docs/sharedNodes/README.md b/v1/docs/sharedNodes/README.md → docs/sharedNodes/README.md
diff --git a/v1/docs/typeNodes/AmountTypeNode.md → docs/typeNodes/AmountTypeNode.md b/v1/docs/typeNodes/AmountTypeNode.md → docs/typeNodes/AmountTypeNode.md
diff --git a/v1/docs/typeNodes/ArrayTypeNode.md → docs/typeNodes/ArrayTypeNode.md b/v1/docs/typeNodes/ArrayTypeNode.md → docs/typeNodes/ArrayTypeNode.md
diff --git a/v1/docs/typeNodes/BooleanTypeNode.md → docs/typeNodes/BooleanTypeNode.md b/v1/docs/typeNodes/BooleanTypeNode.md → docs/typeNodes/BooleanTypeNode.md
diff --git a/v1/docs/typeNodes/BytesTypeNode.md → docs/typeNodes/BytesTypeNode.md b/v1/docs/typeNodes/BytesTypeNode.md → docs/typeNodes/BytesTypeNode.md
diff --git a/v1/docs/typeNodes/DateTimeTypeNode.md → docs/typeNodes/DateTimeTypeNode.md b/v1/docs/typeNodes/DateTimeTypeNode.md → docs/typeNodes/DateTimeTypeNode.md
diff --git a/...ocs/typeNodes/EnumEmptyVariantTypeNode.md → docs/typeNodes/EnumEmptyVariantTypeNode.md b/...ocs/typeNodes/EnumEmptyVariantTypeNode.md → docs/typeNodes/EnumEmptyVariantTypeNode.md
diff --git a/...cs/typeNodes/EnumStructVariantTypeNode.md → docs/typeNodes/EnumStructVariantTypeNode.md b/...cs/typeNodes/EnumStructVariantTypeNode.md → docs/typeNodes/EnumStructVariantTypeNode.md
diff --git a/...ocs/typeNodes/EnumTupleVariantTypeNode.md → docs/typeNodes/EnumTupleVariantTypeNode.md b/...ocs/typeNodes/EnumTupleVariantTypeNode.md → docs/typeNodes/EnumTupleVariantTypeNode.md
diff --git a/v1/docs/typeNodes/EnumTypeNode.md → docs/typeNodes/EnumTypeNode.md b/v1/docs/typeNodes/EnumTypeNode.md → docs/typeNodes/EnumTypeNode.md
diff --git a/v1/docs/typeNodes/EnumVariantTypeNode.md → docs/typeNodes/EnumVariantTypeNode.md b/v1/docs/typeNodes/EnumVariantTypeNode.md → docs/typeNodes/EnumVariantTypeNode.md
diff --git a/v1/docs/typeNodes/FixedSizeTypeNode.md → docs/typeNodes/FixedSizeTypeNode.md b/v1/docs/typeNodes/FixedSizeTypeNode.md → docs/typeNodes/FixedSizeTypeNode.md
diff --git a/v1/docs/typeNodes/HiddenPrefixTypeNode.md → docs/typeNodes/HiddenPrefixTypeNode.md b/v1/docs/typeNodes/HiddenPrefixTypeNode.md → docs/typeNodes/HiddenPrefixTypeNode.md
diff --git a/v1/docs/typeNodes/HiddenSuffixTypeNode.md → docs/typeNodes/HiddenSuffixTypeNode.md b/v1/docs/typeNodes/HiddenSuffixTypeNode.md → docs/typeNodes/HiddenSuffixTypeNode.md
diff --git a/v1/docs/typeNodes/MapTypeNode.md → docs/typeNodes/MapTypeNode.md b/v1/docs/typeNodes/MapTypeNode.md → docs/typeNodes/MapTypeNode.md
diff --git a/v1/docs/typeNodes/NestedTypeNode.md → docs/typeNodes/NestedTypeNode.md b/v1/docs/typeNodes/NestedTypeNode.md → docs/typeNodes/NestedTypeNode.md
diff --git a/v1/docs/typeNodes/NumberTypeNode.md → docs/typeNodes/NumberTypeNode.md b/v1/docs/typeNodes/NumberTypeNode.md → docs/typeNodes/NumberTypeNode.md
diff --git a/v1/docs/typeNodes/OptionTypeNode.md → docs/typeNodes/OptionTypeNode.md b/v1/docs/typeNodes/OptionTypeNode.md → docs/typeNodes/OptionTypeNode.md
diff --git a/v1/docs/typeNodes/PostOffsetTypeNode.md → docs/typeNodes/PostOffsetTypeNode.md b/v1/docs/typeNodes/PostOffsetTypeNode.md → docs/typeNodes/PostOffsetTypeNode.md
diff --git a/v1/docs/typeNodes/PreOffsetTypeNode.md → docs/typeNodes/PreOffsetTypeNode.md b/v1/docs/typeNodes/PreOffsetTypeNode.md → docs/typeNodes/PreOffsetTypeNode.md
diff --git a/v1/docs/typeNodes/PublicKeyTypeNode.md → docs/typeNodes/PublicKeyTypeNode.md b/v1/docs/typeNodes/PublicKeyTypeNode.md → docs/typeNodes/PublicKeyTypeNode.md
diff --git a/v1/docs/typeNodes/README.md → docs/typeNodes/README.md b/v1/docs/typeNodes/README.md → docs/typeNodes/README.md
diff --git a/v1/docs/typeNodes/RegisteredTypeNode.md → docs/typeNodes/RegisteredTypeNode.md b/v1/docs/typeNodes/RegisteredTypeNode.md → docs/typeNodes/RegisteredTypeNode.md
diff --git a/v1/docs/typeNodes/RemainderOptionTypeNode.md → docs/typeNodes/RemainderOptionTypeNode.md b/v1/docs/typeNodes/RemainderOptionTypeNode.md → docs/typeNodes/RemainderOptionTypeNode.md
diff --git a/v1/docs/typeNodes/SentinelTypeNode.md → docs/typeNodes/SentinelTypeNode.md b/v1/docs/typeNodes/SentinelTypeNode.md → docs/typeNodes/SentinelTypeNode.md
diff --git a/v1/docs/typeNodes/SetTypeNode.md → docs/typeNodes/SetTypeNode.md b/v1/docs/typeNodes/SetTypeNode.md → docs/typeNodes/SetTypeNode.md
diff --git a/v1/docs/typeNodes/SizePrefixTypeNode.md → docs/typeNodes/SizePrefixTypeNode.md b/v1/docs/typeNodes/SizePrefixTypeNode.md → docs/typeNodes/SizePrefixTypeNode.md
diff --git a/v1/docs/typeNodes/SolAmountTypeNode.md → docs/typeNodes/SolAmountTypeNode.md b/v1/docs/typeNodes/SolAmountTypeNode.md → docs/typeNodes/SolAmountTypeNode.md
diff --git a/v1/docs/typeNodes/StandaloneTypeNode.md → docs/typeNodes/StandaloneTypeNode.md b/v1/docs/typeNodes/StandaloneTypeNode.md → docs/typeNodes/StandaloneTypeNode.md
diff --git a/v1/docs/typeNodes/StringTypeNode.md → docs/typeNodes/StringTypeNode.md b/v1/docs/typeNodes/StringTypeNode.md → docs/typeNodes/StringTypeNode.md
diff --git a/v1/docs/typeNodes/StructFieldTypeNode.md → docs/typeNodes/StructFieldTypeNode.md b/v1/docs/typeNodes/StructFieldTypeNode.md → docs/typeNodes/StructFieldTypeNode.md
diff --git a/v1/docs/typeNodes/StructTypeNode.md → docs/typeNodes/StructTypeNode.md b/v1/docs/typeNodes/StructTypeNode.md → docs/typeNodes/StructTypeNode.md
diff --git a/v1/docs/typeNodes/TupleTypeNode.md → docs/typeNodes/TupleTypeNode.md b/v1/docs/typeNodes/TupleTypeNode.md → docs/typeNodes/TupleTypeNode.md
diff --git a/v1/docs/typeNodes/TypeNode.md → docs/typeNodes/TypeNode.md b/v1/docs/typeNodes/TypeNode.md → docs/typeNodes/TypeNode.md
diff --git a/v1/docs/typeNodes/ZeroableOptionTypeNode.md → docs/typeNodes/ZeroableOptionTypeNode.md b/v1/docs/typeNodes/ZeroableOptionTypeNode.md → docs/typeNodes/ZeroableOptionTypeNode.md
diff --git a/v1/docs/valueNodes/ArrayValueNode.md → docs/valueNodes/ArrayValueNode.md b/v1/docs/valueNodes/ArrayValueNode.md → docs/valueNodes/ArrayValueNode.md
diff --git a/v1/docs/valueNodes/BooleanValueNode.md → docs/valueNodes/BooleanValueNode.md b/v1/docs/valueNodes/BooleanValueNode.md → docs/valueNodes/BooleanValueNode.md
diff --git a/v1/docs/valueNodes/BytesValueNode.md → docs/valueNodes/BytesValueNode.md b/v1/docs/valueNodes/BytesValueNode.md → docs/valueNodes/BytesValueNode.md
diff --git a/v1/docs/valueNodes/ConstantValueNode.md → docs/valueNodes/ConstantValueNode.md b/v1/docs/valueNodes/ConstantValueNode.md → docs/valueNodes/ConstantValueNode.md
diff --git a/v1/docs/valueNodes/EnumValueNode.md → docs/valueNodes/EnumValueNode.md b/v1/docs/valueNodes/EnumValueNode.md → docs/valueNodes/EnumValueNode.md
diff --git a/v1/docs/valueNodes/EnumValuePayload.md → docs/valueNodes/EnumValuePayload.md b/v1/docs/valueNodes/EnumValuePayload.md → docs/valueNodes/EnumValuePayload.md
diff --git a/...s/valueNodes/InjectableNumberValueNode.md → docs/valueNodes/InjectableNumberValueNode.md b/...s/valueNodes/InjectableNumberValueNode.md → docs/valueNodes/InjectableNumberValueNode.md
diff --git a/...s/valueNodes/InjectableStringValueNode.md → docs/valueNodes/InjectableStringValueNode.md b/...s/valueNodes/InjectableStringValueNode.md → docs/valueNodes/InjectableStringValueNode.md
diff --git a/v1/docs/valueNodes/InjectedValueNode.md → docs/valueNodes/InjectedValueNode.md b/v1/docs/valueNodes/InjectedValueNode.md → docs/valueNodes/InjectedValueNode.md
diff --git a/v1/docs/valueNodes/MapEntryValueNode.md → docs/valueNodes/MapEntryValueNode.md b/v1/docs/valueNodes/MapEntryValueNode.md → docs/valueNodes/MapEntryValueNode.md
diff --git a/v1/docs/valueNodes/MapValueNode.md → docs/valueNodes/MapValueNode.md b/v1/docs/valueNodes/MapValueNode.md → docs/valueNodes/MapValueNode.md
diff --git a/v1/docs/valueNodes/NoneValueNode.md → docs/valueNodes/NoneValueNode.md b/v1/docs/valueNodes/NoneValueNode.md → docs/valueNodes/NoneValueNode.md
diff --git a/v1/docs/valueNodes/NumberValueNode.md → docs/valueNodes/NumberValueNode.md b/v1/docs/valueNodes/NumberValueNode.md → docs/valueNodes/NumberValueNode.md
diff --git a/v1/docs/valueNodes/PublicKeyValueNode.md → docs/valueNodes/PublicKeyValueNode.md b/v1/docs/valueNodes/PublicKeyValueNode.md → docs/valueNodes/PublicKeyValueNode.md
diff --git a/v1/docs/valueNodes/README.md → docs/valueNodes/README.md b/v1/docs/valueNodes/README.md → docs/valueNodes/README.md
diff --git a/v1/docs/valueNodes/RegisteredValueNode.md → docs/valueNodes/RegisteredValueNode.md b/v1/docs/valueNodes/RegisteredValueNode.md → docs/valueNodes/RegisteredValueNode.md
diff --git a/v1/docs/valueNodes/SetValueNode.md → docs/valueNodes/SetValueNode.md b/v1/docs/valueNodes/SetValueNode.md → docs/valueNodes/SetValueNode.md
diff --git a/v1/docs/valueNodes/SomeValueNode.md → docs/valueNodes/SomeValueNode.md b/v1/docs/valueNodes/SomeValueNode.md → docs/valueNodes/SomeValueNode.md
diff --git a/v1/docs/valueNodes/StandaloneValueNode.md → docs/valueNodes/StandaloneValueNode.md b/v1/docs/valueNodes/StandaloneValueNode.md → docs/valueNodes/StandaloneValueNode.md
diff --git a/v1/docs/valueNodes/StringValueNode.md → docs/valueNodes/StringValueNode.md b/v1/docs/valueNodes/StringValueNode.md → docs/valueNodes/StringValueNode.md
diff --git a/v1/docs/valueNodes/StructFieldValueNode.md → docs/valueNodes/StructFieldValueNode.md b/v1/docs/valueNodes/StructFieldValueNode.md → docs/valueNodes/StructFieldValueNode.md
diff --git a/v1/docs/valueNodes/StructValueNode.md → docs/valueNodes/StructValueNode.md b/v1/docs/valueNodes/StructValueNode.md → docs/valueNodes/StructValueNode.md
diff --git a/v1/docs/valueNodes/TupleValueNode.md → docs/valueNodes/TupleValueNode.md b/v1/docs/valueNodes/TupleValueNode.md → docs/valueNodes/TupleValueNode.md
diff --git a/v1/docs/valueNodes/ValueNode.md → docs/valueNodes/ValueNode.md b/v1/docs/valueNodes/ValueNode.md → docs/valueNodes/ValueNode.md
diff --git a/generators/docs/index.ts b/generators/docs/index.ts
@@ -1,10 +1,11 @@
 /**
  * `docs` generator.
  *
- * Runs the docs generator over the v1 spec, then writes the emitted markdown tree to `v1/docs/`
+ * Runs the docs generator over the spec, then writes the emitted markdown tree to `docs/`
  * (GitHub-flavoured pages, relative `.md` links, `README` landing pages per folder). CI re-runs this
  * and fails if the result differs from what is committed, keeping the docs artifact in lockstep with
- * the spec source.
+ * the spec source. Previous majors' docs live on their own maintenance branches; the root landing
+ * page links to them (see `PREVIOUS_MAJOR_DOCS`).
  */
 
 import path from 'node:path';
@@ -21,7 +22,7 @@ import {
     writeRenderMap,
 } from '@codama/fragments';
 
-import { getSpec } from '../../src/v1';
+import { getSpec } from '../../src/spec';
 import { PAGE_EXTENSION } from './constants';
 import { generateDocs } from './generateDocs';
 import type { DocModel } from './types';
@@ -43,8 +44,8 @@ export function generate(): void {
     const model = generateDocs(getSpec());
     const docsMap = getDocsRenderMap(model);
 
-    const outDir = joinPath(REPO_ROOT, 'v1', 'docs');
+    const outDir = joinPath(REPO_ROOT, 'docs');
     deleteDirectory(outDir);
     writeRenderMap(docsMap, outDir);
-    process.stdout.write(`wrote ${docsMap.size} docs files to v1/docs\n`);
+    process.stdout.write(`wrote ${docsMap.size} docs files to docs/\n`);
 }
diff --git a/generators/docs/render/constants.ts b/generators/docs/render/constants.ts
@@ -10,6 +10,15 @@ export const ROOT_TITLE = 'Codama Spec';
 /** Root-page description. */
 export const ROOT_DESCRIPTION = 'The canonical Codama node specification.';
 
+/**
+ * Docs landing pages of previous spec majors, linked from the root page's version line.
+ * Each release line hosts exactly one major, so older docs live on their own maintenance
+ * branches; append one entry here at each major transition.
+ */
+export const PREVIOUS_MAJOR_DOCS: readonly { label: string; url: string }[] = [
+    { label: 'v1', url: 'https://github.com/codama-idl/spec/blob/1.x/v1/docs/README.md' },
+];
+
 /** The display heading for each category group kind - a rendering concern, kept out of the CategoryGroup data. */
 export const GROUP_TITLES: Record<CategoryGroup['kind'], string> = {
     node: 'Nodes',

diff --git a/generators/docs/render/renderPages.ts b/generators/docs/render/renderPages.ts
@@ -22,7 +22,7 @@ import type {
     MarkupRenderer,
     NavRegistry,
 } from '../types';
-import { BLOCK_SEPARATOR, GROUP_TITLES, ROOT_DESCRIPTION, ROOT_TITLE } from './constants';
+import { BLOCK_SEPARATOR, GROUP_TITLES, PREVIOUS_MAJOR_DOCS, ROOT_DESCRIPTION, ROOT_TITLE } from './constants';
 import { isDocChild, linkedEntity, renderType } from './renderType';
 
 /** Shared context threaded through every page renderer. `link` resolves a relative href between two pages. */
@@ -202,6 +202,14 @@ export function renderCategoryIndexPage(category: CategorySpec, ctx: RenderCtx):
     };
 }
 
+/** The root page's version line: the current spec version, plus links to the docs of previous majors. */
+function specVersionLine(version: string, markup: MarkupRenderer): string {
+    const current = `Spec version: ${version}`;
+    if (PREVIOUS_MAJOR_DOCS.length === 0) return current;
+    const others = PREVIOUS_MAJOR_DOCS.map(major => markup.link(major.label, major.url)).join(', ');
+    return `${current} · Other majors: ${others}`;
+}
+
 export function renderRootIndexPage(spec: Spec, ctx: RenderCtx): DocPage {
     const { markup } = ctx;
     const ref: DocRef = { kind: 'rootIndex' };
@@ -228,8 +236,8 @@ export function renderRootIndexPage(spec: Spec, ctx: RenderCtx): DocPage {
         markup.heading(1, ROOT_TITLE),
         // description
         markup.paragraph(ROOT_DESCRIPTION),
-        // version
-        markup.paragraph(`Spec version: ${spec.version}`),
+        // version, with a switcher to the docs of previous majors (hosted on their maintenance branches)
+        markup.paragraph(specVersionLine(spec.version, markup)),
         // legend for the (abstract)/(recursive) heading suffixes
         markup.paragraph(
             `Pages marked ${markup.italic('(abstract)')} document unions: sets of nodes that can be used ` +

diff --git a/generators/index.ts b/generators/index.ts
@@ -3,8 +3,10 @@
  *
  * Runs every registered generator sequentially. Each generator exposes
  * a `generate()` function (sync or async) from its `index.ts`, owns its
- * target output paths, and writes to a versioned subfolder
- * (`v1/...`, future `v2/...`, …) at the repo root.
+ * target output paths, and writes its artifacts (`spec.json`, `schema.json`,
+ * `docs/`) at the repo root. Each release line hosts exactly one spec major,
+ * so the artifacts are unversioned; previous majors live on their own
+ * maintenance branches.
  *
  * Adding a new generator: drop a folder under `generators/`, export a
  * `generate()` from its `index.ts`, then register it in the `GENERATORS`

diff --git a/generators/json-schema/index.ts b/generators/json-schema/index.ts
@@ -1,7 +1,7 @@
 /**
  * `json-schema` generator.
  *
- * Will emit the public `v1/schema.json` JSON Schema artifact from the
+ * Will emit the public `schema.json` JSON Schema artifact from the
  * encoded spec for use by editor tooling and third-party consumers.
  *
  * Currently a no-op stub; the orchestrator runs it but it does nothing

diff --git a/generators/json-spec/index.ts b/generators/json-spec/index.ts
@@ -1,28 +1,29 @@
 /**
  * `json-spec` generator.
  *
- * Emits the canonical `v1/spec.json` artifact from the encoded v1 spec.
+ * Emits the canonical `spec.json` artifact from the encoded spec.
  * CI re-runs this and fails the build if the resulting file differs from
  * what's committed, ensuring the JSON artifact and the TypeScript source
  * stay in lockstep.
  *
- * Future Codama majors add a second `writeSpec('v2', getV2Spec())` line.
+ * Each release line hosts exactly one spec major, so there is exactly one
+ * `spec.json`; previous majors live on their own maintenance branches.
  */
 
 import { writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
-import type { Spec } from '../../src/api';
-import { getSpec as getV1Spec } from '../../src/v1';
+import { getSpec } from '../../src/spec';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 // here = <repo>/generators/json-spec → repoRoot is two levels up.
 const REPO_ROOT = path.resolve(HERE, '../..');
 
-async function writeSpec(major: string, spec: Spec): Promise<void> {
-    const out = path.join(REPO_ROOT, major, 'spec.json');
+export async function generate(): Promise<void> {
+    const spec = getSpec();
+    const out = path.join(REPO_ROOT, 'spec.json');
     const json = JSON.stringify(spec, null, 4) + '\n';
     await writeFile(out, json, 'utf8');
     const nodeCount = spec.categories.reduce((acc, c) => acc + c.nodes.length, 0);
@@ -32,7 +33,3 @@ async function writeSpec(major: string, spec: Spec): Promise<void> {
         `wrote ${path.relative(REPO_ROOT, out)} (${nodeCount} nodes, ${unionCount} unions, ${enumCount} enumerations)\n`,
     );
 }
-
-export async function generate(): Promise<void> {
-    await writeSpec('v1', getV1Spec());
-}
diff --git a/oxfmt.config.ts b/oxfmt.config.ts
@@ -3,7 +3,10 @@ const solanaFmt = require('@solana-config/oxc/oxfmt');
 
 const ignorePatterns = [
     '**/dist/',
-    'v[0-9]*/**',
+    // generated artifacts (machine output)
+    'spec.json',
+    'schema.json',
+    'docs/**',
     '.changeset/**',
     'CHANGELOG.md',
     'pnpm-lock.yaml',

diff --git a/oxlint.config.ts b/oxlint.config.ts
@@ -3,7 +3,10 @@ const solanaConfig = require('@solana-config/oxc/oxlint');
 
 const ignorePatterns = [
     '**/dist/',
-    'v[0-9]*/**',
+    // generated artifacts (machine output)
+    'spec.json',
+    'schema.json',
+    'docs/**',
     '.changeset/**',
     'CHANGELOG.md',
     'pnpm-lock.yaml',

diff --git a/package.json b/package.json
@@ -20,8 +20,7 @@
     "files": [
         "./dist/types",
         "./dist/index.*",
-        "./dist/api.*",
-        "./dist/v1.*"
+        "./dist/api.*"
     ],
     "type": "commonjs",
     "sideEffects": false,
@@ -50,17 +49,6 @@
                 "import": "./dist/api.node.mjs",
                 "require": "./dist/api.node.cjs"
             }
-        },
-        "./v1": {
-            "types": "./dist/types/v1/index.d.ts",
-            "browser": {
-                "import": "./dist/v1.browser.mjs",
-                "require": "./dist/v1.browser.cjs"
-            },
-            "node": {
-                "import": "./dist/v1.node.mjs",
-                "require": "./dist/v1.node.cjs"
-            }
         }
     },
     "scripts": {

diff --git a/v1/schema.json → schema.json b/v1/schema.json → schema.json
@@ -1,7 +1,7 @@
 {
     "$comment": "Generated artifact. Placeholder until the json-schema generator lands.",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://github.com/codama-idl/spec/raw/main/v1/schema.json",
+    "$id": "https://github.com/codama-idl/spec/raw/main/schema.json",
     "title": "Codama IDL",
     "type": "object"
 }
diff --git a/scripts/sync-spec-version.ts b/scripts/sync-spec-version.ts
@@ -1,9 +1,9 @@
 /**
- * Syncs `SPEC_VERSION` (src/v1/version.ts) with the `version` field of package.json.
+ * Syncs `SPEC_VERSION` (src/spec/version.ts) with the `version` field of package.json.
  *
  * Run by the release flow (`pnpm release:version`) right after `changeset version`, so the
  * spec version lands in the same commit as the package bump. `pnpm generate` then refreshes
- * the `v1/` artifacts that embed the version. A unit test asserts the two values never drift.
+ * the generated artifacts that embed the version. A unit test asserts the two values never drift.
  */
 
 import { readFileSync, writeFileSync } from 'node:fs';
@@ -12,7 +12,7 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const VERSION_FILE = path.join(REPO_ROOT, 'src', 'v1', 'version.ts');
+const VERSION_FILE = path.join(REPO_ROOT, 'src', 'spec', 'version.ts');
 
 const { version } = JSON.parse(readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8')) as { version: string };
 const content = readFileSync(VERSION_FILE, 'utf8');

diff --git a/v1/spec.json → spec.json b/v1/spec.json → spec.json
diff --git a/src/api/types.ts b/src/api/types.ts
@@ -2,8 +2,8 @@
  * Public types describing the shape of a Codama spec.
  *
  * These types are version-agnostic — the same shape describes a Codama v1
- * spec, a v2 spec, etc. Versioned content (concrete nodes, enumerations,
- * unions, categories) lives under `src/v<n>/`. The first half of
+ * spec, a v2 spec, etc. The current major's content (concrete nodes,
+ * enumerations, unions, categories) lives under `src/spec/`. The first half of
  * this file declares the type-expression vocabulary; the second half
  * declares the spec-content shape (attributes, nodes, unions,
  * enumerations, nested unions, categories).

diff --git a/src/index.ts b/src/index.ts
@@ -1,12 +1,10 @@
 /**
  * `@codama/spec` — entry point.
  *
- * Re-exports the latest stable Codama major's public surface. Today that's
- * `@codama/spec/v1`; future Codama majors will add their own subpaths
- * (`@codama/spec/v2`, …) and the entry point will track the latest.
- *
- * Consumers wanting a stable, version-pinned import should always use the
- * subpath form (`@codama/spec/v1`).
+ * Re-exports the spec surface of this release line's Codama major from
+ * `./spec`. Each release line hosts exactly one major: older majors are
+ * published from their own maintenance branches and obtained via npm
+ * versions (e.g. `@codama/spec@^1` for the v1 spec) — see RELEASING.md.
  */
 
-export * from './v1';
+export * from './spec';
diff --git a/src/v1/enumerations.ts → src/spec/enumerations.ts b/src/v1/enumerations.ts → src/spec/enumerations.ts
@@ -1,5 +1,5 @@
 /**
- * Named enumerations for the Codama v1 spec.
+ * Named enumerations for the Codama spec.
  *
  * Anywhere a node attribute would otherwise be an inline string-literal union
  * (e.g. `endian: 'be' | 'le'`), the union is lifted to a named enumeration