The project folder

The project folder is the unit of work. Created by init. Operated on from inside. Portable as a zip.

my-handbook/
├── config.yml             # project metadata + wiki generator + demo questions
├── schema.md              # wiki conventions (types, naming, frontmatter)
├── wiki-instructions.md   # LLM prompt template — portable across generators
├── README.md              # human-facing readme
├── data/                  # raw inputs: PDFs, MD, TXT, CSV, command outputs
├── skills/                # one subfolder per skill (SKILL.md + tool)
├── wiki/                  # the articles — both generated and human-edited
└── .local-agents-build/   # build artifacts (RAG index, manifest staging — gitignored)

Folder roles

Folder	Owner	Contents	Regenerated by?
data/	human	raw files (PDFs, MD, images, CSVs, anything)	n/a
wiki/	shared	one markdown article per input source, plus index.md — wiki generate writes here, humans edit here too	wiki generate (per-article; frozen: true opts out)
skills/	human	SKILL.md folders (one subdir per skill)	n/a
.local-agents-build/	system	RAG chunk index, raw command outputs, embedding cache	build

What's in git, what's in the share zip

	git	share zip
config.yml, schema.md, wiki-instructions.md, README.md	✓	✓
data/	✓	✓
skills/	✓	✓
wiki/	✓	✓
.local-agents-build/	✗ (gitignored)	✓ (RAG index only)
Model + embedding (in ~/.config/local-agents/)	✗	only if --self-contained

wiki/ is committed so collaborators can review the LLM's output via git diff — the safety net for the regen-on-wiki generate behavior.

Single-folder wiki ownership

• wiki/ is the only folder for articles. Both wiki generate (LLM) and humans write there.
• Re-running wiki generate <name> overwrites that article. Pin a hand-edited article by adding frozen: true to its frontmatter — wiki generate then skips it.
• There is no customwiki/ second folder. If you want to keep a specific article hand-edited, mark it frozen.

Name-mapping convention

Every input has a name. The same name shows up in three places:

Input	Becomes	Article
data/return-policy.pdf	.local-agents-build/raw/return-policy.txt (extracted)	wiki/return-policy.md
commands: [{ name: oncall, run: ... }]	.local-agents-build/raw/oncall.json	wiki/oncall.md

File names are slug-cased (lowercase, hyphens). Slugification is idempotent. Collisions fail loud at wiki generate time.

Two layers of state

• Project state (in the folder): everything user-facing — sources, commands, wiki, RAG index, skills.
• Machine state (~/.config/local-agents/): just the model GGUF and the embedding ONNX. Shared across every project on the host.

A project is self-contained except for the model dependency — which can be bundled into the share zip via --self-contained.

Why a folder, not a global store

• Portable. Zip the folder, send it, the recipient has everything.
• Git-friendly. Version, branch, PR, diff your knowledge base.
• Multi-project by convention. A user has many projects; each is its own dir.
• No global state to leak between projects. A command defined in one project doesn't affect another.