{"_id":"@apd1034/cairn","name":"@apd1034/cairn","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@apd1034/cairn","version":"0.2.0","description":"JavaScript reference implementation for the Cairn portable knowledge format.","license":"MIT","type":"commonjs","main":"js/cairn.js","bin":{"cairn-js":"npm/bin/cairn-js"},"scripts":{"test":"node js/test-vectors.js"},"keywords":["knowledge-graph","markdown","yaml","cairn"],"gitHead":"af51283cb5284014559431ccc04219bc3aa3efef","_id":"@apd1034/cairn@0.2.0","_nodeVersion":"26.0.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-Y6PZHWRthKtgZXkB5wIPYTs9JnpD+i1YiLNkrC/VVvhjgeGVC8fzDxn6Y6WbSvCqKXX3Bvnov5qqJs1+tB3f7Q==","shasum":"a5c3678c5b68642663547e2b77248cba8dd2a582","tarball":"https://registry.npmjs.org/@apd1034/cairn/-/cairn-0.2.0.tgz","fileCount":19,"unpackedSize":32942,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDcIlqaq7pUGlIxYAkFrPcaUj/i4l736ihQs2zIrx9XwAiBrnDARrqvTp9d10zAVTpLfy4PiLnhZkqOTf+im8oi9Fw=="}]},"_npmUser":{"name":"apd1034","email":"APD1034@GMAIL.COM"},"directories":{},"maintainers":[{"name":"apd1034","email":"APD1034@GMAIL.COM"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cairn_0.2.0_1781975863548_0.4681610686827018"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-20T17:17:43.435Z","0.2.0":"2026-06-20T17:17:43.684Z","modified":"2026-06-20T17:17:43.867Z"},"maintainers":[{"name":"apd1034","email":"APD1034@GMAIL.COM"}],"description":"JavaScript reference implementation for the Cairn portable knowledge format.","keywords":["knowledge-graph","markdown","yaml","cairn"],"license":"MIT","readme":"# Cairn\n\n**A portable knowledge format — durable identity, verifiable relationships, just files.**\n\n> Cairn v0.2.0 — Project-agnostic specification, examples, tools, and agent skill.\n\n[![CI](https://github.com/apd1034/cairn/actions/workflows/ci.yml/badge.svg)](https://github.com/apd1034/cairn/actions/workflows/ci.yml)\n\nCairn is an open standard for representing project knowledge as a directory of plain Markdown files. Each concept is one file. The file path is the concept's identity. There is no SDK, no runtime, no database, and no required service — only Markdown, YAML frontmatter, and relationships that can be inspected, queried, and verified.\n\n![Cairn: the logical evolution of OKF](assets/cairn-logical-evolution-of-okf.png)\n\n## Why Cairn Exists\n\nFile-based knowledge formats solved the right problem: knowledge should live beside the systems it describes, remain readable without tooling, and work naturally with git. But first-generation formats left structural gaps:\n\n- Links did not distinguish human-verified relationships from tool guesses.\n- Path-only identity could not detect silent drift after a referenced concept changed.\n- Concurrent edits to frontmatter had no deterministic merge behavior.\n- Minimalism was claimed in prose, not proven with a small parser.\n- Compliance was often treated as an all-or-nothing repository score.\n\nCairn keeps the useful part — one concept per file — and hardens it for production-scale knowledge graphs.\n\n## What You Get\n\n- **A core specification:** [SPECIFICATION.md](SPECIFICATION.md)\n- **Self-describing schemas:** [schemas/](schemas/)\n- **Examples:** [examples/](examples/)\n- **Reference parsers:** [tools/reference-parser/](tools/reference-parser/)\n- **Validator, indexer, and auditor:** [tools/](tools/)\n- **Installable CLI:** `cairn validate`, `cairn index`, `cairn audit`, `cairn migrate`, `cairn merge`, `cairn corpus`\n- **Shared test vectors:** [test-vectors/](test-vectors/)\n- **JavaScript reference package:** [js/](js/) and [package.json](package.json)\n- **Project migration agent:** [tools/project-agent/](tools/project-agent/)\n- **Report-writing agent:** [tools/report-agent/](tools/report-agent/)\n- **Agent Skills package:** [skills/cairn-project-migration/](skills/cairn-project-migration/)\n- **Migration guide:** [migration-guides/project-analysis.md](migration-guides/project-analysis.md)\n- **RFC process:** [RFC/](RFC/)\n\n## The Cairn Concept\n\nA concept is a Markdown file with YAML frontmatter.\n\n```yaml\n---\ntype: schemas/concept.md\ntitle: Payment Service\ndescription: Handles payment authorization and settlement.\nstatus: active\ntags: [service, payments]\ntimestamp: 2026-06-20T00:00:00Z\nhash: <optional sha256 of the body>\naliases:\n  - services/billing.md\nrelations:\n  - type: depends_on\n    target: databases/payments.md\n    confidence: declared\n    note: Human-reviewed architecture dependency.\n  - type: references\n    target: APIs/checkout.md\n    confidence: inferred\n    note: Inferred from import CheckoutClient in src/payments/client.ts:12.\n---\n\n# Payment Service\n\nOrdinary Markdown body.\n```\n\nOnly `type` and `title` are required. Everything else increases clarity, traceability, or compliance level.\n\n## Core Ideas\n\n1. **One concept, one file.** The file path is identity inside a bundle.\n2. **No required tooling.** A Cairn bundle remains useful with only a filesystem and text editor.\n3. **Relations have provenance.** Every relation says whether it is `declared` by a human or `inferred` by a tool.\n4. **Integrity is optional and verifiable.** A `hash` can verify the body content without a central registry.\n5. **Renames do not break identity.** `aliases` carry old paths forward.\n6. **Types are Cairn concepts.** A `type` points to a schema concept under `schemas/`.\n7. **Merges are deterministic.** Relation arrays dedupe by `(type, target)`, tags union, and scalar fields resolve by timestamp.\n8. **Compliance is per concept.** Cairn never collapses a repository into one compliance score.\n9. **Minimalism is proven.** The core parser is under 60 lines in both Python and TypeScript.\n10. **Core stays small.** Memory, embeddings, workflows, and permissions belong in companion layers, not the core format.\n\n## Repository Layout\n\n```text\ncairn/\n├── README.md\n├── SPECIFICATION.md\n├── schemas/\n├── examples/\n├── assets/\n├── tools/\n│   ├── validate/\n│   ├── index/\n│   ├── auditor/\n│   ├── project-agent/\n│   ├── report-agent/\n│   └── reference-parser/\n├── skills/\n│   ├── cairn-project-migration/\n│   └── cairn-report-writing/\n├── migration-guides/\n├── reports/\n└── RFC/\n```\n\n## Quick Start\n\nInstall locally from this repository:\n\n```sh\npython3 -m pip install -e .\n```\n\nValidate this repository as a Cairn bundle:\n\n```sh\ncairn validate .\n```\n\nGenerate a structured index with backlinks:\n\n```sh\ncairn index .\n```\n\nRun a per-concept compliance audit:\n\n```sh\ncairn audit .\n```\n\nParse a concept with the minimal reference parser:\n\n```sh\ncairn parse SPECIFICATION.md\n```\n\nMerge three concept versions deterministically:\n\n```sh\ncairn merge base.md ours.md theirs.md --output merged.md --conflicts-json conflicts.json\n```\n\nThe legacy script paths are still available for direct use:\n\n```sh\npython3 tools/validate/validate.py .\npython3 tools/index/index.py .\npython3 tools/auditor/audit.py . --json-only\n```\n\n## Bring A Project Up To Cairn Standard\n\nUse the project migration agent. It scans a target project read-only by default and stages proposed Cairn concepts outside the source project.\n\n```sh\ncairn migrate /path/to/project\n```\n\nDefault output:\n\n```text\ncairn-runs/<project>-<timestamp>/\n├── cairn-proposed/\n└── reports/CAIRN_MIGRATION_<timestamp>.md\n```\n\nTo write staging artifacts inside the target project, opt in explicitly:\n\n```sh\ncairn migrate /path/to/project --write-into-target\n```\n\nThe agent:\n\n- detects candidate services, modules, APIs, data models, workflows, ownership files, and docs\n- stages one concept per candidate\n- uses `<needs author input>` when source text does not support a description\n- marks generated relations as `confidence: inferred`\n- cites concrete evidence in relation notes\n- writes a timestamped migration report\n- stops before modifying the real project knowledge base\n\n## Agent Skills Support\n\nThis repo includes Agent Skills-compatible packages:\n\n```text\nskills/\n├── cairn-project-migration/\n└── cairn-report-writing/\n```\n\nThe project migration skill stages concepts and migration reports:\n\n```text\ncairn-project-migration/\n├── SKILL.md\n├── scripts/\n├── references/\n├── assets/\n└── evals/\n```\n\nThe report-writing skill standardizes Cairn migration and audit reports:\n\n```text\ncairn-report-writing/\n├── SKILL.md\n├── scripts/\n├── references/\n└── agents/\n```\n\nUse them with any Agent Skills-compatible client by installing or copying the relevant skill directory into that client's skills directory.\n\nBoth skills follow the Agent Skills progressive disclosure model:\n\n- `SKILL.md` contains concise trigger and workflow instructions.\n- `references/` contains the detailed contract or standard.\n- `scripts/` contains reusable automation where deterministic output matters.\n- `assets/` contains supporting static files where needed.\n- `evals/` contains expected behavior test cases where useful.\n\n## Compliance Levels\n\nCompliance is reported per concept only.\n\n| Level | Requirement |\n|---|---|\n| 1 | `type` + `title` |\n| 2 | + `description`, `status`, `tags` |\n| 3 | + at least one typed `relations` entry where relevant |\n| 4 | + `type` resolves to an existing schema concept |\n| 5 | + every relation carries `confidence`; zero broken relations or orphaned aliases |\n| 6 | + `hash` present and verified against current body content |\n\nThere is no whole-bundle compliance score.\n\n## Test And Release Readiness\n\nThis repository includes fixture-based regression tests and GitHub Actions CI. The tests cover valid bundles, invalid bundles, index generation, audit JSON output, and read-only project migration staging.\n\nRun the local suite:\n\n```sh\npython3 -m unittest discover -s tests\nnpm test\npython3 -m compileall cairn_cli.py tools skills/cairn-project-migration/scripts skills/cairn-report-writing/scripts\ncairn validate .\ncairn index .\ncairn audit . --json-only\n```\n\nRelease candidates should pass CI on Python 3.10, 3.11, and 3.12 before tagging.\n\n## Proof Artifacts\n\nCairn now keeps claims tied to executable artifacts:\n\n- `tools/merge/merge.py` implements deterministic three-way concept merges.\n- `tests/test_cairn_tools.py` includes fixture, vector, and randomized merge determinism tests.\n- `test-vectors/` defines shared hash, merge, and compliance expectations.\n- `js/cairn.js` is a JavaScript reference parser/hash implementation checked against the same hash vectors.\n- `docs/security/THREAT_MODEL.md` documents YAML, path, and future `cairn://` trust boundaries.\n- `tools/corpus/evaluate.py` provides a repeatable harness for migration-agent corpus runs.\n\n## Version Stability\n\nCairn uses the same semantic version for the format specification and reference tooling. Versions before `1.0.0` are standard-candidate releases: concept files should remain readable, but frontmatter fields and merge semantics may still change through the RFC process. Breaking format changes require a new minor version before `1.0.0` and a new major version after `1.0.0`.\n\n## Frequently Asked Questions\n\n### Is Cairn a database?\n\nNo. Cairn is a file format. You can index it into a database if you want, but the bundle remains valid without one.\n\n### Do I need the tools?\n\nNo. Tools are optional. A Cairn bundle is readable and usable as plain Markdown. The tools validate, index, audit, and migrate faster.\n\n### Why not JSON, RDF, or a graph database?\n\nCairn optimizes for repository-native knowledge: reviewable diffs, git history, simple files, and human readability. It can be exported to graph systems, but it does not require them.\n\n### What is relation provenance?\n\nEvery relation has `confidence: declared | inferred`. `declared` means a human asserted the relation. `inferred` means a tool derived it from evidence such as an import, foreign key, route, or config dependency.\n\n### What does the optional hash protect?\n\n`hash` is the SHA-256 digest of the concept body, excluding frontmatter. It lets consumers detect drift or tampering after a concept is referenced.\n\n### Can I rename a concept?\n\nYes. Move the file and add the old path to `aliases`. Consumers can resolve references to old paths through aliases.\n\n### Can I add embeddings, memory, workflows, or permissions?\n\nNot in core. Put those in companion specifications that reference Cairn concepts by path or `cairn://` URI.\n\n### How do merges work?\n\nFrontmatter has deterministic merge rules. Relations dedupe by `(type, target)`, tags union, aliases union, and scalar fields resolve by the later `timestamp`.\n\n### Is OKF required?\n\nNo. Cairn is standalone. It borrows the useful file-based idea and adds relation provenance, integrity, deterministic merges, and proof of minimalism.\n\n### Can this be used in any language or project type?\n\nYes. Cairn concepts are plain files. The migration agent detects common project signals across many ecosystems, but the format itself is project-agnostic.\n\n## Governance\n\nSpec changes go through [RFC/](RFC/). RFCs are Cairn concepts with `type: schemas/rfc.md`. A proposal is `draft` until accepted, then `active`.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","readmeFilename":"README.md","_rev":"1-cd73ed6a94565fef317e6d2b6bef3068"}