--- name: getting-started-hosted description: Set up the flow of intentions (foi) on this computer and link a project to the foi hub at foi.voidlore.com, so its component graph shows on the web, on the phone and in Claude chat. Use when the human says "set up the flow of intentions from foi.voidlore.com", asks to set up foi here, to put a project on the hub, or to see it on the web or a phone. --- # Set up the flow of intentions from foi.voidlore.com You are setting up three things on the human's computer: **foi** (the project's component graph, a folder of notes usually called `docs`), **foi-mcp** (foi's tools for agents like you), and **foi-link** (it sends the component graph to the hub at https://foi.voidlore.com, so the human sees it on the web, on the phone and in Claude chat). The human is often **not a developer**. Talk plainly, one step at a time; say what a command does before you run it; never ask them to edit a file by hand. Their quickstart is https://foi.voidlore.com/start. Rules that hold throughout: - **Never handle the hub's token.** `foi-link login` puts it in the macOS Keychain; the human approves in the browser. You never read, print or copy it. - **Do not run git** unless `xcode-select -p` succeeds. On a Mac without the developer tools, any `git` command pops up an installer dialog. Nothing in this setup needs git. - **No sudo, no Homebrew, no Xcode, no Go.** The installer needs none. - **Projects live in `~/Documents/GitHub/`** (where GitHub Desktop keeps them). macOS guards Documents: it asks once whether Terminal, and later foi-link, may read it. The human clicks **Allow**; tell them before it happens. - Ask before anything that lets the hub write (step 8) and before moving the human's folders. ## 0. Make sure your shell finds the commands Everything is installed in `~/.local/bin`, which may not be on your shell's PATH yet (a fresh install, or a shell started before it). An older `foi` elsewhere on PATH must not win either. So begin **every** shell command with: ```sh export PATH="$HOME/.local/bin:$PATH" ``` (Agents whose shell keeps no variables between commands: put it in front of each command, joined with `;` or `&&`.) ## 1. Installed? ```sh export PATH="$HOME/.local/bin:$PATH"; foi --version; foi-link version ``` - Both print a version, foi at `0.1.0-rc3` or newer: go to step 2. - `command not found`, or foi older than `0.1.0-rc3`: tell the human you will install foi (no password needed, nothing outside their home folder changes), then run: ```sh curl -fsSL https://foi.voidlore.com/install.sh | sh -s -- --skills ``` Then run step 1 again. If it says `this Mac runs macOS 11`, the Mac is too old for foi (macOS 12 or newer is needed): stop and tell the human. ## 2. Linked to the hub? ```sh export PATH="$HOME/.local/bin:$PATH"; foi-link status ``` If the `login:` line says `not logged in`: 1. Tell the human: "A browser page will open with a code. Check that it matches the code I show you, then click **Approve**. If you are not signed in to foi.voidlore.com, sign in with the emailed link first." 2. Run `foi-link login`. It waits (up to 10 minutes) until the human approves. In Claude Code run it with a 600000 ms timeout or in the background, or ask the human to type `! foi-link login` at Claude Code's prompt. Show the human the code it prints. 3. It ends with `Linked to foi.voidlore.com as `. ## 3. Ask the human about the project Ask in one message: 1. Is this a **new** project, or **existing** code or notes? 2. Its **name** (for a new one; you make it lowercase with dashes, e.g. `garden-planner`). 3. For an existing one: **where is it?** Then pick the folder: - **New:** `mkdir -p ~/Documents/GitHub/` and work in `~/Documents/GitHub/`. - **Existing:** work where it is (usually `~/Documents/GitHub/`); do not move it. - **In iCloud Drive, or in a Documents folder that syncs with iCloud** ("Desktop & Documents Folders" on): it works while the files stay on the Mac. Ask the human to Control-click the project folder in Finder and choose **Keep Downloaded** (or turn off Optimize Mac Storage). Every command below runs **in the project folder**: `cd ~/Documents/GitHub/`. If macOS asks to let Terminal (or Claude Code) access the Documents folder, the human clicks **Allow**. ## 4. Make the vault The vault is the component graph's folder inside the project. Call it `docs`, unless the project already has a `docs` folder that is not a vault (no `docs/component.md`): then call it `graph`. Below, `` is that name. - **`/component.md` exists already:** it is a vault; go to step 5. - **New project:** ```sh export PATH="$HOME/.local/bin:$PATH"; foi init docs ``` Then write the root vision **with** the human: ask what the project is for, who it is for, and what "done" looks like; draft a few short paragraphs; show them; when they agree, write it (body on stdin, no `Status:` line in it): ```sh export PATH="$HOME/.local/bin:$PATH"; foi note write --status draft --agent claude-code docs . vision < vision.txt ``` (Use your own agent id instead of `claude-code`; delete `vision.txt` afterwards.) - **Existing code or notes:** ```sh export PATH="$HOME/.local/bin:$PATH"; foi convert propose "$PWD" ``` It only reads the project and writes `.foi/graph-proposal.md` (an older foi names it `.foi/forest-proposal.md`) and `.foi/apply.sh`. Summarise the proposal for the human in plain words: the components it found and each OPEN decision. Do not decide the OPEN rows for them and do not run `apply.sh` yourself (the converting-a-project skill's rule; an older foi calls it converting-a-forest): when they agree, ask them to run it (in Claude Code they type `! sh .foi/apply.sh `). Then: ```sh export PATH="$HOME/.local/bin:$PATH"; foi gate pin && foi lint ``` ## 5. The graph id ```sh export PATH="$HOME/.local/bin:$PATH"; foi forest id ``` It prints the component graph's id (`f-` and 16 hex digits), minting it the first time (`foi init` already did, for a new project). The hub knows the project by it. A newer foi calls this command foi graph id; the name above works in both. ## 6. Give your agents foi's tools (foi-mcp) Use absolute paths: apps started from the Dock do not have `~/.local/bin` on their PATH and do not expand `~`. **Claude Code**, in the project folder (local scope: only this folder, on this computer, no approval prompt, nothing committed): ```sh export PATH="$HOME/.local/bin:$PATH"; claude mcp add --scope local foi -- "$HOME/.local/bin/foi-mcp" --vault "$PWD/" ``` Check with `claude mcp list` (it shows `foi` as connected). The foi tools load in the **next** Claude Code session: tell the human to type `/exit` and start `claude` again in this folder. If it says `MCP server foi already exists`: `claude mcp remove --scope local foi`, then add it again. **Codex**: add to `~/.codex/config.toml` (one entry per project, so name it after the project): ```toml [mcp_servers.foi-] command = "/Users//.local/bin/foi-mcp" args = ["--vault", "/Users//Documents/GitHub//"] ``` (or `codex mcp add foi- -- /Users//.local/bin/foi-mcp --vault /Users//Documents/GitHub//`). Codex may say the folder is not a git repository: that is fine, continue (`codex exec --skip-git-repo-check` for one-off runs). Never run `git init` on a Mac without the developer tools. **Any other MCP client** (Claude Desktop, Cursor, ...), in its MCP JSON: ```json { "mcpServers": { "foi": { "command": "/Users//.local/bin/foi-mcp", "args": ["--vault", "/Users//Documents/GitHub//"] } } } ``` Agents without MCP use the `foi` command line directly; that works too. Tell the human the one rule agents cannot cross: **only a person agrees a layer.** Agents land their work as draft or done; foi refuses an agent's `agreed`. The human agrees on the board, or by asking Claude chat (that is their own instruction, recorded as theirs "via Claude"). Likewise only a person corrects a release recorded with the wrong outcome (a take-over recorded as failed): ask Claude chat, or at the terminal `foi claim history --outcome failed`, then `foi claim correct --outcome infra --reason "a take-over" --agent --kind human`. ## 7. Link the project to the hub ```sh export PATH="$HOME/.local/bin:$PATH"; foi-link add --name ``` It prints `Linked ... as (graph f-...)` and, for a project in Documents, that macOS will ask once to let foi-link read the folder: tell the human that step 9 is when it asks. ## 8. Writes from the web, the phone and Claude (ask first) Until the human allows it, the hub can only **read** the project. Explain: "If you turn this on, you (on the web or phone), Claude chat with write access, and people you invite can post on the board, edit notes and take claims in this project. Each write runs here on your computer through foi's own checks. You can turn it off any time with `foi-link writes off `." If they want it: ```sh export PATH="$HOME/.local/bin:$PATH"; foi-link writes on ``` ## 9. Keep the link running On a Mac: ```sh export PATH="$HOME/.local/bin:$PATH"; foi-link install-launchd ``` Before running it, tell the human: "macOS will now ask to let foi-link access your Documents folder: click **Allow**." It starts the link now and at every login, waits for its first read of each project (that is when macOS asks) and says `Read and uploaded `. If it says `macOS did not allow foi-link to read this folder`, the human clicked Don't Allow: walk them through the lines it prints (System Settings > Privacy & Security > Files and Folders > foi-link > Documents Folder on, then `foi-link down && foi-link install-launchd`). foi-link is not signed by a registered Apple developer, so after a foi-link upgrade macOS may ask again; that is expected. On Linux run `foi-link up` as a service (a systemd user unit); in a pinch, in a terminal left open. ## 10. Check, and show the human ```sh export PATH="$HOME/.local/bin:$PATH"; foi-link doctor ``` It should end `Everything looks right` (or only `warn` notes; `not uploaded yet` clears within a minute: run it again). Every `FIX` line says what to run; do that and run doctor again. Then tell the human: 1. Open https://foi.voidlore.com/projects (on the Mac or the phone): the project shows, with its component graph. 2. To ask Claude about it from claude.ai or the Claude phone app: on claude.ai, Settings, Connectors, **Add custom connector**, address `https://foi.voidlore.com/mcp`, then **Connect** and allow it on the hub page that opens. Then ask: "What are my agents doing?" 3. If anything looks wrong later: `foi-link doctor`, and send its output to whoever helps them. ## When something goes wrong | What you see | What it means | What to do | |---|---|---| | `command not found: foi` (or foi-link, foi-mcp) | not installed, or not on this shell's PATH | step 0's `export PATH=...` line; if still missing, step 1's install line | | macOS dialog "The git command requires the command line developer tools" | something ran `git` | the human clicks **Cancel**; nothing here needs git | | install: `this Mac runs macOS 11` | the Mac is too old for foi | stop; macOS 12 or newer is needed | | install: `could not download` | offline, or the hub is restarting | check the internet connection; try again in a minute | | `foi ... is older than 0.1.0-rc3` | an old foi | step 1's install line replaces it | | `foi init: target ... exists and is not empty` | that folder exists | if it has `component.md` it is already a vault (go to step 5); otherwise use the vault name `graph` (step 4) | | `... is not a graph root (no component.md)` (an older foi says `forest root`) | not the vault folder | give the vault (`docs` or `graph`), not the project folder | | `note write: ... is not pinned under the gate` | a converted project without pins | `foi gate pin `, then write again | | `foi-link add: ... is the project folder` | the project folder was given | `foi-link add --name ` | | `foi-link add: ... is not a foi vault` | no vault yet | step 4 | | `this computer is not logged in to the hub` | not linked | step 2 | | `the code expired before it was approved` | nobody approved within 10 minutes | `foi-link login` again; the human approves sooner | | `the link was denied in the browser` | the human clicked Deny | `foi-link login` again; click **Approve** | | `could not reach foi.voidlore.com` | offline, or the hub is restarting | check the internet connection; try again in a minute | | `the hub does not know this computer's token` / `the hub revoked this computer's link` | the link was revoked (Account page) or logged out | `foi-link login` (the link restarts by itself) | | `the hub needs a newer foi-link` | an old foi-link | step 1's install line (it restarts the link) | | `graph f-... is already linked here as ...` | a copied vault shares its id | move `/.foi/state/graph_id` and `forest_id` aside, `foi forest id `, add again | | `the name ... is taken` | another vault has that name | `--name ` | | `foi-link up is already running in a terminal` | the link runs in a terminal | `foi-link down`, then `foi-link install-launchd` | | `launchctl bootstrap: ...` | launchd refused the agent | `foi-link uninstall-launchd`, then `foi-link install-launchd`; if it still fails, the human logs out of the Mac and in again, then retry | | `claude: command not found` | Claude Code is not installed in this shell | use step 6's Codex or JSON form, or skip step 6 (agents can use `foi` directly) | | `claude mcp list` shows foi failed | a wrong path in the entry | check `ls ~/.local/bin/foi-mcp` and `ls /component.md`; remove and add again with absolute paths | | `claude mcp list` shows fio failed (`fio-mcp` not found) | an entry from before the rename; the installer removed fio-mcp | `claude mcp remove --scope local fio`, then step 6 adds foi | | `macOS did not allow foi-link to read this folder (operation not permitted)` | the human clicked Don't Allow, or a foi-link upgrade needs the grant again | System Settings > Privacy & Security > Files and Folders > foi-link > Documents Folder on (or Full Disk Access), then `foi-link down && foi-link install-launchd` | | `foi-link doctor`: `macOS does not let this terminal read it` | Terminal (or Claude Code's app) was refused Documents | System Settings > Privacy & Security > Files and Folders > Terminal > Documents Folder on | | `foi-link doctor`: `in a folder that syncs with iCloud` | Desktop & Documents in iCloud, or iCloud Drive | Finder: Control-click the project folder, **Keep Downloaded** | | `foi-link doctor`: `another foi first ... too old` | an older foi earlier on PATH | the line doctor prints (`rm ...` or `brew uninstall foi`), then a new terminal window | Still stuck: ask the human to send `foi-link doctor`'s whole output to whoever helps them (it holds no secrets).