Editing the wiki

How a change gets from your editor to internal.beliefengines.io.

This site is the be-internal repo. docs/ is the source of truth; pushing to main is the deploy. People and agents both edit it the same way.

First time

git clone git@github.com:beliefengines/be-internal.git
cd be-internal && nvm use && npm install

Then type the name of the area you want to work on — be-category-name. That is the entry point: it puts you in the folder with the agents running and the advisor attached. No setup command first.

The loop

┌──────────┐   ┌───────────────┐   ┌──────────────┐   ┌──────────────┐
│ 1 edit   │ → │ 2 check       │ → │ 3 push       │ → │ 4 show       │
│ docs/*.md│   │ npm run       │   │ git commit   │   │ npm run show │
│ in your  │   │   validate    │   │ git push     │   │ opens the    │
│ editor   │   │               │   │   origin main│   │ live site    │
└──────────┘   └───────────────┘   └──────────────┘   └──────────────┘
                                     push = live

No branches, no PRs. Claude does steps 2, 3 and 4 itself. You write. Broke something? It’s in git — git log -- docs/<page>.md to find the old version.

Page rules

• Markdown first. Plain .md. .mdx only when a component earns it.
• 500 words max. npm run validate fails a page that’s over. Split it.
• Structure goes in a diagram, not prose. ASCII in a code fence first (like the one above). Excalidraw only when ASCII can’t carry it — export SVG beside the page, keep the .excalidraw source next to it.
• Simpler wins. Short sentences. Real names and numbers.

Full conventions live in the repo’s CLAUDE.md.