Migrate agent configs and guidance to codeassembly

[williamthorsen]

Migrate agent guidance to codeassembly

Problem

General agent guidance files (AGENTS.md, CLAUDE.md) are version-controlled in williamthorsen/configs.macos, but they belong with the agent tooling in codeassembly. This creates a split-brain situation where the agent system's content (skills, subagents) lives in one repo and the guidance that shapes agent behavior lives in another.

Context

• The codeassembly agents CLI already installs skills and subagents via copy/symlink to platform directories
• configs.macos manages user-specific dotfile symlinks via ensure-user-configuration.sh
• ~/.agents/ is currently a directory symlink to configs.macos, containing both AGENTS.md (general guidance) and preferences.yaml (user-specific)
• The Claude CLAUDE.md currently contains shared formatting preferences that belong in the common AGENTS.md

Solution

1. Add a content/guidance/ directory to the agents package with shared and platform-specific guidance files
2. Extend the agents CLI install command to install guidance files: shared AGENTS.md to ~/.agents/, platform-specific files to each platform's home directory. Track them in the manifest for drift detection.
3. Merge writing style and prompt formatting from ~/.claude/CLAUDE.md into the shared AGENTS.md. Reduce CLAUDE.md to a thin shim.
4. Update configs.macos: remove migrated guidance files, change ~/.agents/ from a directory symlink to an individual file symlink for preferences.yaml only

Acceptance criteria

• content/guidance/shared/AGENTS.md contains the full shared guidance (including merged formatting preferences)
• content/guidance/_platforms/claude/CLAUDE.md is a thin shim referencing ~/.agents/AGENTS.md
• content/guidance/_platforms/rovodev/AGENTS.md is a thin shim referencing ~/.agents/AGENTS.md
• codeassembly-agents install copies/symlinks guidance files to the correct locations
• codeassembly-agents install --link symlinks guidance files
• Guidance files appear in the manifest with drift detection
• codeassembly-agents uninstall removes installed guidance files
• codeassembly-agents status reports guidance file status
• New/modified behavior in this change is covered by tests

[williamthorsen]

Machine-specific preferences strategy

preferences.yaml needs to differ per machine (e.g., commit prefix conventions differ between home and work). Proposed approach:

Layout in configs.macos

macos/_HOME/_agents/
  preferences.yaml            # shared defaults (canonical reference)
  preferences.home.yaml       # full file for home machines
  preferences.work.yaml       # full file for work machine

Resolution

Introduce a MACHINE_PROFILE env var (set once per machine in ~/.zshenv or a local dotfile). The setup script selects the right file:

cp macos/_HOME/_agents/preferences.${MACHINE_PROFILE}.yaml \
   macos.live/_HOME/_agents/preferences.yaml

Why full copies instead of overlays

The file is small (~15 lines). Maintaining two complete copies avoids YAML merge complexity and keeps each file independently readable.

Relationship to #377

Files that contain shared guidance (AGENTS.md, CLAUDE.md) migrate to codeassembly. Files that are inherently user/machine-specific (preferences.yaml, settings.json, hooks) stay in configs.macos and use MACHINE_PROFILE to resolve per-machine variants.

[williamthorsen]

Updated: CONFIG_PROFILE instead of MACHINE_PROFILE

Revised the env var name from MACHINE_PROFILE to CONFIG_PROFILE. The axis is person + context, not machine identity.

Expected values: personal, work, diana (and potentially others).

Hardware differences (Intel vs Apple Silicon) are better handled by detection (uname -m) than by profile, keeping the two concerns independent.

[williamthorsen]

Insights from orchestrated run 20260403-181824Z

checkSymlinkSafety is critical for the configs.macos migration path. Without it, ~/.agents/ being a directory symlink (the current configs.macos setup) causes the install to silently write through the symlink into the symlinked target rather than failing with a clear error. The safety check was initially missing and caught during review.

readManifest shifted from silent-reset to fail-fast on corrupt JSON. The original pattern caught JSON.parse errors and returned an empty manifest, silently discarding all installation records. This was changed to throw, which is a deliberate trade-off toward data safety — callers now see the corruption rather than silently losing track of installed files.

Latent partial-uninstall bug identified. When some shared guidance entries are skipped (user-modified) and others removed, the manifest retains references to the deleted files. Currently harmless (only one shared file), but would surface as stale "missing" entries if another shared file is added. Tracked in #388.