Add RCF Lite to an existing repository

You have a repository with code already in it, and you want RCF Lite wired in beside that code. Running rcf init in the project root gives you the document scaffold, the MCP server entry, the agent instructions and the agent's knowledge space, and it does all of that without reading or writing a line of your source. This page sets out exactly what init touches, what it leaves alone, and how to prove both on your own repository.

Before you start

• rcf-lite installed: npm install -g rcf-lite on Node.js 24 or later. On an older Node the install delivers a placeholder release with no CLI, so check node -v first. npx rcf-lite <verb> works if you would rather not install it. Full install steps are in Wire your agent.
• A repository you are willing to let rcf init write into. The next section says exactly what it touches.

Initialise the project

Run init in the project root:

rcf init

Init scaffolds the rcf/ tree, including a knowledge space at rcf/knowledge/ and a gitignored per-clone operator profile at rcf/.identity/. It merges the rcf MCP server entry into the project-root .mcp.json, writes a managed instructions block into CLAUDE.md and AGENTS.md, and writes a managed block into .gitignore. On a fresh project it writes both instructions files; if you already have one of them, it refreshes that file in place and does not invent the other. Re-running init is idempotent and refreshes the wiring without touching an existing tree.

On an existing repository, the contract is:

There is no --dry-run on init. The honest preview is to start from a clean tree, run it, and read the diff:

git status
rcf init
git diff

Everything init writes is an ordinary working-tree change. Nothing is staged or committed.

Set the boundary honestly: init is an entry point, nothing more. It does not retrofit traceability onto existing code, and it does not make a repository compliant on its own. You get the method wired in, your existing work untouched, and a scaffold that fills in from the next piece of work. If you want the tree without the agent wiring, rcf init --no-agent-setup scaffolds it and prints the manual steps.

Prove the contract

The standard tools work on the scaffold from the moment init writes it, and together with git they turn the table above from a claim into something you have checked yourself.

rcf audit view

That serves the tree at http://127.0.0.1:4373/ by default for reading in a browser, live-updating as the files change. It binds to 127.0.0.1 only and has no authentication. What you see is the scaffold init just wrote, and nothing of yours.

rcf define validate

Validate walks the tree, reports schema violations and broken references, and exits 3 when the tree is unsound. On the untouched scaffold it comes back clean, with an informational notice about the placeholder text your agent has not filled in yet.

Put the three checks together and the safety contract is demonstrated, not described: rcf audit view shows you everything init wrote, rcf define validate proves the tree it wrote is sound, and the git diff from a clean start shows every changed path on disk, none of them yours. Backing out is just as visible: delete rcf/, remove the rcf entry from .mcp.json, and revert the managed blocks in .gitignore and the instructions files, and the repository is exactly as it was.

Where this leaves you

Your working tree now carries the RCF Lite scaffold and the agent wiring, sitting beside code that init never read. The chain fills in from the next piece of work you drive with your coding agent; Wire your agent covers handing the project over and what the agent does from there.

For the document types and how they link, see document types.