CLAUDE

Baseworks Knowledge Base — Claude Instructions

When to Load This File

If you are working on anything related to the Baseworks Obsidian vault (baseworks-kb-shared-brain) — regardless of whether you are in Claude Desktop, Claude Code, or a terminal session — read this file before proceeding.

Git Workflow

This vault is a Git repository synced to GitHub: p-oancia/baseworks-kb-shared-brain

Branch: main — this is the ONLY branch. Do NOT create or push to any other branch.

At the START of each session:

git checkout main
git pull origin main

At the END of each session (after changes):

git add .
git commit -m "Description [Claude Code on MACHINE_NAME]"
git push origin main

Multiple machines share this repo. Always pull before working and push when done.

Repo location varies by machine:

Patrick’s Mac: ~/Obsidian/baseworks-kb-shared-brain/
Asia’s Mac: ~/Obsidian/baseworks-kb-shared-brain/
VPS (baseworks-agents): /srv/baseworks/knowledge-base/

Shared Infrastructure Context

For any session involving server infrastructure, backups, Docker services, or VPS configuration, read the shared context file first:

00-inbox/claude-code-shared-context.md

This file is the single source of truth for infrastructure state across all Claude Code instances (Patrick’s Mac, VPS, Asia’s machines). After making infrastructure changes, update it and push so other instances stay in sync.

Inbox Protocol

Patrick and Asia communicate with each other through Claude via inbox files. Check and update these inboxes as part of any workflow step that produces something for the other person to review:

Patrick’s inbox: 00-inbox/patrick-inbox.md
Asia’s inbox: 00-inbox/asia-inbox.md
Full workflow protocol: 00-inbox/WORKFLOW-PROTOCOL.md

When a document is ready for someone’s review, add an item to their inbox before ending the session. See WORKFLOW-PROTOCOL.md for the exact format.

Attribution: Every inbox item must include a machine identity source line after the heading. Each machine’s ~/.claude/CLAUDE.md defines its identity. Full identity table and format examples are in 00-inbox/WORKFLOW-PROTOCOL.md.

Git commits: Always append the machine identity tag to commit messages (e.g., [Claude Code on Patrick's Mac]).

Voice Guides

For any writing task, load the appropriate guides from 03-resources/voice-guides/ before drafting:

All writing: VOICE-GUIDE-UNIFIED.md — core Baseworks voice, applies to all contexts
Writing as Patrick: also load VOICE-GUIDE-PATRICK.md
Writing as Asia: also load VOICE-GUIDE-KSENIA-ASIA.md
Proposing a guide change: read VOICE-GUIDE-GOVERNANCE.md first

Check Inboxes at Session Start

When this file is loaded at the start of a vault-related session, check the inbox of the person you are working with and briefly surface any open (unchecked) items before moving on to the main task. Don’t interrupt the work — just note what’s pending so nothing gets forgotten.

If working with Asia: check 00-inbox/asia-inbox.md
If working with Patrick: check 00-inbox/patrick-inbox.md

Post-Edit Workflow

When Asia or Patrick signals they have finished editing a document and want to hand it off, run the post-edit workflow described in 00-inbox/WORKFLOW-PROTOCOL.md.

Code Belongs in the Changelog Repo

This vault is for knowledge, context, and content — not site code.

If you write or modify any of the following during a vault session, it belongs in the baseworks-changelog repository (~/Documents/baseworks-changelog/ on Patrick’s and Asia’s Macs, /srv/baseworks/changelog/ on the VPS), not in the vault:

WordPress plugins, mu-plugins, or theme files for any *.baseworks.com site
Fluent Snippets / code snippets for any site
Plugin-settings-stored code (Perfmatters header/footer, Elementor custom code, etc.)
Server scripts or configs that run on the web host or agents VPS and affect a site
WP-CLI commands or SQL helpers targeting any site

Vault-native code is fine — scripts under scripts/ that operate on the vault itself (sync, wikilink check, index build), content-generation helpers tied to a specific vault document, and the agent-system under 03-resources/agent-system/.

If site code ends up in the vault by accident, move it to the correct sites/[site]/... subfolder in baseworks-changelog, commit it there, and leave a wikilink/reference from the vault note that needed it. The authoritative location for site code is always the changelog repo.

See CLAUDE-INSTRUCTIONS.md in baseworks-changelog for the full folder taxonomy (mu-plugins vs code-snippets vs plugin-settings-code, etc.) and the mirror-from-server checklist.

Backup Policy

All backups must go to Backblaze B2 off-site storage. Never leave backups only on the server’s local disk. For ad-hoc commands, bucket table, and full procedures, see 00-inbox/claude-code-shared-context.md.

Frontmatter Rules for Vault Files

The KB site (kb.baseworks.com) is built from this vault by site/scripts/sync-content.mjs. Broken YAML frontmatter can degrade the site (the script auto-repairs bad YAML by stripping it and generating a title from the filename, but metadata like tags and dates will be lost). Follow these rules:

Every frontmatter block must have opening and closing --- delimiters:
```
---
title: "My Note Title"
created: 2026-03-07
---
```
Do NOT use markdown syntax inside frontmatter — no ## title:, no # headings, no bold/italic.
Do NOT add vault_path to frontmatter — the sync script generates it automatically. Adding it manually causes duplicate YAML keys.
No duplicate keys — each YAML key (title, tags, created, etc.) must appear exactly once.
Quote titles that contain colons, dashes, or special characters:
```
title: "Quebec Language Law — Bill 96 / Bill 101"
```

If the sync script encounters broken frontmatter, it will auto-repair (strip the bad YAML, regenerate a title from the filename, preserve body content). The file will still appear on the KB site but will lose its metadata. A warning appears in the GitHub Actions build log.

Wikilink Standards

Obsidian’s power comes from bidirectional linking — the graph view, backlinks panel, and discoverability all depend on proper wikilinks. Follow these rules whenever creating or modifying vault files:

Always use wikilinks for cross-references

Use [Display Name](/target/) whenever referencing another vault file. Never use backtick paths (`02-areas/path/to/file.md`) for content that should be linked — backtick paths are invisible to Obsidian’s graph and backlinks.
Exception: Backtick paths are appropriate in technical documentation (agent system docs, deployment guides, shell instructions) where the path is a filesystem reference, not a navigational link.

When creating a new directory with content

Always create an index.md in the directory — this gives other files a wikilink target for the collection
The index should list the directory’s contents as wikilinks and link back to the parent area
Frontmatter should include title, created, and relevant tags

When adding a new file

Add wikilinks in the new file’s ## Related section pointing to related content in other areas
Update any existing files that should link back to the new file (check the parent index, related guides, and hub files)
Use Obsidian’s shortest-path resolution: [filename](/filename/) or [Display Name](/filename/) when the filename is unique; use relative paths ([file](/folder/file/)) only when needed for disambiguation

Linting

A wikilink checker script exists at scripts/check-wikilinks.py. Run it to find broken links:

python3 scripts/check-wikilinks.py              # Full scan
python3 scripts/check-wikilinks.py --changed     # Only changed files

Run the full scan periodically and after any structural changes (renaming files, moving directories, creating new areas).

Vault Relationship Index

A SQLite database (vault-index.db at vault root, gitignored) indexes all wikilinks, tags, and frontmatter metadata. Rebuilt automatically by the post-sync hook. Useful queries: backlinks (SELECT source_path FROM links WHERE target_path = ?), tag search (SELECT file_path FROM tags WHERE tag = ?), orphans, broken links. Full schema in scripts/build-vault-index.py. To rebuild manually: python3 scripts/build-vault-index.py (incremental) or --full.

Claude Code Skills

Skills (slash commands) are reusable workflows in .claude/skills/. Available skills, creation protocol, and detailed docs are in 03-resources/claude-code-skills/index.md.

Project-Specific Guidelines

Each document type or ongoing project may have its own guidelines file. Check for one before starting:

Session summaries: 02-areas/educational-programs/study-groups/_session-summary-guidelines.md
Campaign creation: 02-areas/communications/campaigns/_campaign-creation-guidelines.md (also available as /create-campaign skill)