BeaconFold

BeaconFold is an npm create-style scaffold for source-backed LLM Wiki instances.

The repository root is the generator package, not a generated knowledge base. A generated instance owns the Markdown-first knowledge system (raws, wiki, graph, claims, projects, outputs, system, tools, and optional interfaces/viewer).

Root Layout

cli/        create-beaconfold and beaconfold package commands
templates/  extensible instance templates
viewer/     reusable read-only Astro viewer copied into instances when enabled

Package-level files such as package.json, README.md, LICENSE, .gitignore, and AGENTS.md stay at the root. Instance directories must stay under templates/<name>/files/ or inside generated projects.

Create An Instance

npm create beaconfold@latest ./Nervia

Providing a target path uses the recommended LLM Wiki defaults and does not open a long questionnaire. Run npm create beaconfold@latest without a target for the short wizard, or add -- --advanced when you need to choose language, source strictness, privacy boundary, and feature flags.

Local development entrypoints:

pnpm install
pnpm test
node cli/bin/create-beaconfold ./Nervia
node cli/bin/create-beaconfold --advanced
node cli/bin/beaconfold sync --target ./Nervia --dry-run

The default template is templates/llm-wiki. It renders instance-owned files from templates/llm-wiki/render, copies template-owned skeleton files from templates/llm-wiki/files, writes beaconfold.viewer.json from templates/llm-wiki/template.json, and copies the root viewer/ source to interfaces/viewer/ when the viewer feature is enabled.

Generated Instance Shape

A typical instance created from llm-wiki contains:

AGENTS.md
README.md
beaconfold.instance.json
beaconfold.viewer.json
purpose.md
index.md
log.md
raws/
wiki/
claims/
graph/
projects/
outputs/
system/
tools/
interfaces/viewer/   optional, when viewer is enabled

The instance viewer is read-only. Product navigation is driven by the generated beaconfold.viewer.json and should surface the knowledge library, source ledger, relation graph, claims, projects, and outputs. Template-maintenance routes such as system docs and tools are not product navigation in instance mode.

Template Sync

Template sync is run from the generator package, not from the repository root as an instance:

node cli/bin/beaconfold sync --target /path/to/Nervia --dry-run
node cli/bin/beaconfold sync --target /path/to/Nervia --apply

Sync updates template-owned files and skips instance-owned files such as README.md, purpose.md, index.md, log.md, AGENTS.md, wiki/home.md, active ledgers, and viewer config.

Verification

pnpm test
npm pack --dry-run

For a generated instance:

cd /path/to/Nervia
./tools/verify-contracts
pnpm --dir interfaces/viewer build

The viewer remains an adapter. It reads repository files for display and must not crawl sources, ingest knowledge, promote review state, or write instance files.