Forge Mac mini — Obsidian vault setup

Goal

Get Obsidian (1.12.4+ for CLI support) running on the Forge Mac mini, pointed at the local clone of offplan-online/os, with the committed .obsidian/ baseline applied automatically and the Obsidian CLI on PATH. Once this lands, Forge sessions read and write the same vault state Roman sees on his primary Mac without any per-machine drift.

This is the proof case for the "repo as canonical store" architectural bet: a second operator's machine should bootstrap from a single git clone + brew install --cask obsidian and have a working vault.

Tasks

• [x] F1. Confirm Forge has git + gh + brew installed (per repo's first-time-setup checklist in CLAUDE.md). If not, install via Homebrew. If gh is unauthenticated on Forge, run gh auth login once. Done 2026-05-11 (SSH): all three at /opt/homebrew/bin/; gh authenticated as romanvolumevision with repo + read:org scopes.
• [x] F2. Clone offplan-online/os into ~/code/offplan-online/os on Forge (matches Roman's primary-machine path). If a clone already exists, git pull --ff-only. Do NOT clone into iCloud-managed paths (~/Documents/, ~/Desktop/, ~/Library/CloudStorage/...) — per CLAUDE.md § iCloud/FileProvider warning; the atomic session-ID claim semantics break under FileProvider. Done 2026-05-11 (SSH): clone already present at /Users/forge/code/offplan-online/os (non-iCloud); was stuck at bacc540 due to HTTPS credential issue — fixed by gh auth setup-git; pulled to 42cc34b.
• [x] F3. brew install --cask obsidian on Forge. If it's already there at an older version, brew upgrade --cask obsidian. Verify version: mdls -name kMDItemVersion /Applications/Obsidian.app — needs to be ≥ 1.12.4 for CLI support (GA shipped 2026-02-27). Done 2026-05-11 (Roman, ahead of dispatch): Obsidian.app at /Applications/Obsidian.app, version 1.12.7 (installer 1.12.7) confirmed by obsidian version post-F5.
• [x] F4. Open ~/code/offplan-online/os as a vault in Obsidian on Forge. The committed .obsidian/ baseline should load automatically (Better Markdown Links plugin prompts to install — accept; optional Dataview prompts likewise — accept if desired). Verify the prompt fires; if it doesn't, the baseline didn't land cleanly and we have a P10 bug to file back to the vault workstream. Done 2026-05-11 (Roman, ahead of dispatch): vault loaded showing 206 files / 24 folders, matches main. The pre-pull stub .obsidian/*.json files were removed and replaced cleanly by the canonical P10 baseline via git pull — no P10 bug.
• [x] F5. Enable the Obsidian CLI on Forge: Obsidian → Settings → General → Advanced → Command line interface → toggle on → "Register CLI". Then add to ~/.zshrc on Forge: ``` export PATH="$PATH:/Applications/Obsidian.app/Contents/MacOS" ``` Reload the shell and verify with obsidian version. Expected output is a version string ≥ 1.12.4. If the binary isn't found, check that Obsidian.app is in /Applications/ (not ~/Applications/ or a DMG) — the CLI binary lives inside the .app bundle at Contents/MacOS/obsidian. Done 2026-05-11: PATH export appended idempotently to ~/.zshrc via SSH; CLI toggle enabled manually by Roman via GUI; obsidian version returns 1.12.7 (installer 1.12.7). Note: the setting is under General → Advanced (not directly under General as docs suggested) — UI nesting confirmed via the binary's own error message before the toggle.
• [x] F6. Smoke-test the CLI against the vault: cd ~/code/offplan-online/os && obsidian files | head -20 should list workstreams + plans + sessions. obsidian search query="repo-as-canonical-store" should return matches. If both work, the Forge side of the architecture is live. Done 2026-05-11: obsidian search query="repo-as-canonical-store" returned 5 hits across workers/notion-sync/README.md, workstreams/forge-vault-setup.md, workstreams/repo-as-canonical-store-vault.md, workstreams/repo-as-canonical-store-flip.md, workstreams/done/operator-aware-handoff-resume.md. Architecture proven: second Mac reads + searches the same canonical store via a CLI that didn't exist a few weeks ago.
• [x] F7. Document the Forge-specific paths and CLI verification in docs/conventions/obsidian.md (the file that ships in vault workstream P12). One short subsection: "Forge setup recipe" with the exact commands above, so any future operator setting up a second machine follows the same path. Cross-link from this workstream's "What's Next" once P12 lands. Done 2026-05-11: shipped in the same branch vault/p12-audit-links-and-conventions that lands P12 of the vault workstream. docs/conventions/obsidian.md § Forge setup recipe captures the verbatim F1–F6 sequence (env check via which, gh auth setup-git for HTTPS credential helper, brew install --cask obsidian, idempotent PATH append, the Settings → General → Advanced → Command line interface GUI step, end-to-end smoke test with obsidian version + obsidian search).

What's Next

Workstream complete (2026-05-11). F1–F6 shipped in the original SSH session that created this workstream; F7 shipped on branch vault/p12-audit-links-and-conventions alongside vault P12. Status flipped active → done. The proof-of-architecture is live: Forge bootstrapped from git clone + brew install --cask obsidian + GUI CLI toggle, no per-machine drift; the recipe is documented for any future secondary-machine bootstrap in docs/conventions/obsidian.md § Forge setup recipe.

No follow-on. If /handoff or /resume ever migrate from the Python frontmatter path to the Obsidian CLI (the forward pointer captured in docs/conventions/obsidian.md), that's a fresh workstream — not this one.

Key Context

• Plan: repo-as-canonical-store — Forge setup isn't an explicit phase in the plan, but it's the proof-of-architecture for the canonical-store bet. If Forge can't bootstrap from a clone + brew install, the architecture has a leak we need to find.
• Blocked by: repo-as-canonical-store-vault — P10 ships .obsidian/{app,appearance,community-plugins,core-plugins}.json to the repo; Forge inherits via git pull.
• Obsidian CLI background: Obsidian shipped its official CLI in 1.12.0 (early access, 2026-02-10) and made it generally available in 1.12.4 (2026-02-27). 100+ commands across 8 categories (files, properties, search, tags, links, daily, plugins, dev). Eventually /handoff and /resume may shell out to it for vault operations (frontmatter manipulation, link audit, etc.) — but that integration is downstream of this setup, not blocking it. Docs: https://obsidian.md/help/cli.
• Sergei doesn't need this workstream. Sergei runs locally on his own Mac, not on Forge. This is Roman-only setup. If Sergei ever onboards onto Forge sessions, he reads this workstream + the docs/conventions/obsidian.md recipe.
• No Forge access wiring in this repo. offplan-online/os doesn't ship the SSH config, forge skill, or GUPPI helpers. Roman runs F1–F7 manually via whatever access pattern he already uses (likely a GUPPI-provided shortcut from a separate repo). If we ever want CI-style verification of Forge setup, that's a separate workstream involving a GUPPI/os integration layer.
• Reversibility. Every task here is safely revertible. F1 (installs) survive uninstall; F2 (clone) is rm -rf; F3 (brew install) is brew uninstall --cask obsidian; F4–F6 don't write anything outside Obsidian's per-user state. F7 is a docs edit on this repo, reviewable as a PR.
• Realistic estimate: under 1 hour, single session. Most of it is "wait for brew install".

Session Log

• forge-vault-setup-f7-build (2026-05-11): F7 shipped + status flipped active → done. Folded the verbatim F1–F6 SSH sequence into docs/conventions/obsidian.md § Forge setup recipe in the same branch (vault/p12-audit-links-and-conventions) that ships vault workstream P12. Cross-link from there back to this workstream; cross-link from here forward to the convention doc. Workstream closes — F1–F7 all [x]. Total span: same day as creation (2026-05-11). The architectural bet — "second operator's machine bootstraps from clone + brew install with zero per-machine drift" — is proven and documented for the third operator.
• RT-260511-04 (2026-05-11): Workstream created and F1–F6 shipped same session. Heavy SSH automation from Roman's primary Mac: env check, repo gh auth setup-git for HTTPS credential helper (deploy SSH key on Forge only had guppi access — couldn't be used for offplan-online/os), discarding Obsidian's auto-generated .obsidian/*.json stubs to allow the canonical P10 baseline to apply via git pull, idempotent PATH export to ~/.zshrc. Roman flipped the Settings → General → Advanced → Command line interface toggle manually (only non-scriptable step). Verified end-to-end: obsidian version returns 1.12.7; obsidian search query="repo-as-canonical-store" returns 5 vault hits including this workstream file. Only F7 (docs in docs/conventions/obsidian.md) remains and is blocked-on vault P12.