and-core is the standalone home for &ND (AEON Native Document).
&ND is a pedantic prose language. Pronounced “amperand”… with a silent G. Markdown tries to be forgiving. &ND is not.
&ND is a deterministic, fail-closed document language designed for structured document content,
editor integration, canonicalization, and future conformance-tested implementations.
- docs/spec/README.md — version-stage index for
&NDspec tracks - docs/spec/v1/README.md — the current v1 spec bundle
- docs/spec/v2/README.md — the active v2 proposal track
- docs/spec/v1/and-implementation-guide.md — parser-author guidance and recommended architecture
- docs/spec/v1/and-public-api.md — proposed stable package surface for external consumers
- docs/spec/v1/fmt-and-reference.md — proposed AES-facing
fmt.andvocabulary and model boundary - docs/tooling/playground.md — local playground direction and usage
- docs/tooling/html-renderer.md — AST-to-HTML projection contract
- vscode/ — first-pass VS Code language prototype
- playground/ — static parser/canonical/preview playground prototype
- cts/README.md — conformance test suite plan and fixture layout
- implementations/README.md — future parser/emitter implementation home
- examples/README.md — future example documents and interoperability samples
- CONTRIBUTING.md — contribution workflow for spec, CTS, and implementation changes
The repository is currently spec-and-CTS first:
- the v1 language spec has been migrated in from the design workspace
- canonical, implementation, and editor-support documents are present
- CTS fixtures are machine-readable and indexed
- a reference parser adapter validates strict accept/reject fixtures, expected ASTs, and expected error codes
- an executable v2 proposal lane validates promoted syntax, cross-version boundaries, canonical round trips, resource budgets, and HTML projection
- a smaller reference subset adapter demonstrates capability-scoped CTS participation
- an initial root package surface is available through
index.mjs - CI runs the repository safety checks and both CTS adapters
The repository currently tracks two active language stages:
&ND Core v1is in draft stage&ND Core v2is in proposal stage
Stage meanings in this repository:
- draft: semantics and behavior may still change, including breaking changes, while design and CTS pressure continue
- proposal: exploratory design work where shape and boundaries are intentionally fluid
Current working focus is v2 proposal development. v1 remains editable and may still change until
it is formally published by aeonite-org.
- docs/spec/v1/and-core-proposal.md
- docs/spec/v1/and-canonical-rules.md
- docs/spec/v1/and-implementation-guide.md
- docs/spec/v1/and-vscode-support.md
- docs/spec/v1/and-ast-contract.md
If you are here to understand the language itself:
If you want to contribute to ongoing design direction:
- docs/spec/README.md
- docs/spec/v2/README.md
- docs/spec/v2/and-core-v2-proposal.md
- docs/spec/v2/and-ast-contract.md
If you want to build a parser or canonical emitter:
- docs/spec/v1/and-core-proposal.md
- docs/spec/v1/and-implementation-guide.md
- docs/spec/v1/and-ast-contract.md
- cts/README.md
- implementations/README.md
If you want to connect &ND into the AES ecosystem:
If you want to work on editor tooling:
If you want to extend or audit the CTS:
- run the reviewed v2 proposal-to-draft promotion gate
- keep the executable v2 proposal lane independent from the normative v1 fixture index
- continue validating and refining v1 draft behavior under implementation pressure
- keep conformance seeds, CTS fixtures, and reference reports moving together
npm test— runs the repository safety checks, CTS adapters, adapter example, canonical checks, and CLI smoke checksnpm run playground— serves the local playground athttp://localhost:4173/playground/npm run playground:check— verifies playground wiring, parser budgets, and parser/canonical smoke behaviornpm run check:html-renderer— verifies the reference AST-to-HTML projectionnpm run check:vscode— verifies the VS Code prototype manifest, grammar, and language configurationnpm run html:report— writes reference HTML renderer output snapshots tocts/reports/npm run and -- check examples/minimal.and— checks one document with the local CLInpm run and -- check examples/minimal.and --budget maxLineLength=120— checks with an explicit parser budgetnpm run and -- check path/to/proposal.and --version v2— opts the CLI into the v2 proposal parsernpm run and -- diagnostics examples/minimal.and --json— emits parser-backed diagnostics for editor tooling- open the repo in VS Code and run
.vscode/launch.json→Run &ND VS Code Prototype— launches the current editor prototype againstvscode/samples/ npm run vscode:package— stages a dependency-free unpacked VS Code extension bundle underartifacts/npm run and -- parse examples/minimal.and --json— emits a parsed ASTnpm run and -- parse examples/minimal.and --json --spans— emits an AST with source spansnpm run and -- canonical examples/minimal.and --profile standalone— emits canonical textnpm run and -- render-html examples/minimal.and— emits an escaped HTML fragmentnpm run and -- render-html examples/minimal.and --document --out output.html— writes a complete HTML documentnpm run and -- render-html path/to/proposal.and --version v2 --image-base-url https://docs.example/guide/proposal.and— resolves relative image sources against an explicit HTTP(S) document base- CLI parser budgets use repeatable
--budget name=valueflags. Supported names aremaxDocumentSize,maxLineLength,maxNestingDepth,maxInlineDepth,maxTableColumns,maxBlockSize,maxBlockCount,maxListItemCount, andmaxLinkTargetLength. - CLI failures include stable
errorCodevalues and line/column diagnostics where available npm run check:no-local-paths— blocks workstation-specific path leaks in tracked filesnpm run check:spec-layout— verifies the expected spec bundle layout and local Markdown linksnpm run check:cts-fixtures— validates the CTS fixture index and fixture JSON shapenpm run check:cts-seed-coverage— verifies that all normative spec seeds are represented in the CTS indexnpm run check:reports— verifies generated CTS/canonical/HTML report artifacts are freshnpm run check:canonical-emitter— emits canonical text for supported CTS AST fixtures and reparses itnpm run check:html-renderer— checks escaped HTML fragment/full-document output and fail-closed behaviornpm run check:public-api— verifies the root package surface for parse, inline parse, diagnostics, canonical emission, and HTML projectionnpm run check:v2-guidance— verifies the migration and consumer-convention boundaries remain completenpm run cli:smoke— verifies the local CLI check, parse, and canonical commandsnpm run canonical:report— writes canonical emitter output snapshots tocts/reports/npm run html:report— writes HTML renderer output snapshots tocts/reports/npm run cts:run— loads the CTS fixture manifest and emits the current placeholder/adapted run reportnpm run cts:run:example— runs the copyable baseline adapter examplenpm run cts:run:subset— runs the current reference subset adapter against the CTSnpm run cts:run:reference— runs the first reference parser adapter against the CTSnpm run cts:run:v2:proposal— runs v2 proposal fixtures plus v1/v2 version-boundary checksnpm run cts:report:example— writes a JSON CTS report artifact for the baseline adapter examplenpm run cts:report:subset— writes a JSON CTS report artifact for the reference subset adapternpm run cts:report:reference— writes a JSON CTS report artifact for the reference parser adapternpm run cts:report:all— regenerates all parser and canonical report artifactsnpm run precommit:check— runs the current repository safety checks together
The GitHub Actions workflow in .github/workflows/ci.yml runs:
npm run precommit:checknpm run cts:run:referencenpm run cts:run:subsetnpm run cts:run:v2:proposalnpm run check:canonical-emitter