chore(ai): initialize project notes and Claude tooling surfaces

Replace the seed notes.org with project-specific context (layout, install modes, task tracker location, recent inflection point). Bring in the synced template surfaces (protocols, workflows, scripts, references, retrospectives, someday-maybe) as tracked content for this content/documentation project.

1 files changed, 155 insertions, 0 deletions

diff --git a/.ai/scripts/cross-agent-comms/cross-agent-discover.md b/.ai/scripts/cross-agent-comms/cross-agent-discover.md
new file mode 100644
index 0000000..95134bb
--- /dev/null
+++ b/.ai/scripts/cross-agent-comms/cross-agent-discover.md
@@ -0,0 +1,155 @@
+# cross-agent-discover
+
+**Purpose.** Enumerate available cross-agent destinations — local projects on
+this machine and remote projects on tailnet peers. Validates SSH reachability
+for cross-machine destinations before reporting them as usable.
+
+## Usage
+
+```
+cross-agent-discover [--enumerate-remote] [--no-cache] [--peer <name>]
+```
+
+No args required for the common case (local enumeration + peer reachability).
+
+### Flags
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--enumerate-remote` | off | SSH into each peer and list projects under `~/projects/*/.ai/`. Off by default because SSH adds latency; turn on when you want to see what's available on a remote machine you haven't fully configured. |
+| `--no-cache` | off | Skip the 5-minute cache; force fresh discovery. |
+| `--peer <name>` | (all) | Limit to a single peer from `peers.toml`. |
+| `--json` | off | Machine-readable output. |
+
+## Output
+
+### Default
+
+```
+$ cross-agent-discover
+Local (ratio):
+  career, claude-templates, clipper, danneel, documents, elibrary,
+  finances, health, homelab, jr-estate, kit, little-elisper,
+  philosophy, website  [14 projects]
+
+Peers (from ~/.config/cross-agent-comms/peers.toml):
+  velox.local      reachable    (last seen 2 sec ago)
+  bastion.local    UNREACHABLE  (ssh exit 255: connection refused)
+```
+
+### With `--enumerate-remote`
+
+```
+$ cross-agent-discover --enumerate-remote
+Local (ratio):
+  ... (as above)
+
+velox.local (reachable):
+  career, homelab  [2 projects]
+```
+
+## Configuration
+
+Reads `~/.config/cross-agent-comms/peers.toml`:
+
+```toml
+# Each peer is a remote machine reachable via SSH (typically over Tailscale).
+
+[peers.velox]
+host = "velox.local"
+ssh_user = "cjennings"
+
+[peers.bastion]
+host = "bastion.local"
+ssh_user = "cjennings"
+```
+
+Peers entries describe machines, NOT projects. Projects are enumerated
+on-demand under `~/projects/*/.ai/` either locally or via SSH.
+
+## Cache
+
+Successful discovery results are cached at
+`~/.cache/cross-agent-comms/discovery.json` for 5 minutes. Repeated invocations
+within the window read from cache.
+
+`--no-cache` forces a fresh probe. Useful when adding a new peer or after a
+network change.
+
+## SSH reachability check
+
+For each peer, runs:
+
+```
+ssh -o ConnectTimeout=2 -o BatchMode=yes <user>@<host> true
+```
+
+`BatchMode=yes` prevents interactive password prompts — peers that don't have
+key-based auth set up are reported as UNREACHABLE.
+
+If `--enumerate-remote` is set, on success runs:
+
+```
+ssh <user>@<host> 'ls -d ~/projects/*/.ai/ 2>/dev/null'
+```
+
+## Failure modes
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Peer reported UNREACHABLE | Tailscale not connected, SSH key not authorized, host firewalled | `tailscale status`; `ssh -v <peer>` to debug. |
+| Local list is empty | Glob misresolved, or `~/projects/` doesn't exist | Check `ls -d ~/projects/*/.ai/`. |
+| `--enumerate-remote` slow | Cold cache, slow tailnet, many peers | First run is slow, subsequent runs hit cache. Use `--peer <name>` to scope. |
+| Peer unexpectedly missing from output | Not in `peers.toml`, or `peers.toml` malformed | `cat ~/.config/cross-agent-comms/peers.toml` and validate. |
+
+## HALT awareness
+
+Checks `~/.config/cross-agent-comms/HALT` at start. If HALT exists, prints a
+prominent banner before normal output:
+
+```
+$ cross-agent-discover
+⚠ HALT ACTIVE — cross-agent comms paused
+  Reason: <reason from HALT file body, if any>
+  Resume with: cross-agent-resume
+
+(enumeration continues normally — HALT does not suppress visibility)
+
+Local (ratio):
+  career, claude-templates, ...
+
+Peers:
+  velox.local      reachable
+```
+
+Discover is read-only. Like `cross-agent-status`, it always runs so the user
+keeps visibility into what destinations exist regardless of halt state. The
+banner makes the halt state impossible to miss.
+
+If the HALT file exists but is unreadable, print a warning banner and
+continue.
+
+See `cross-agent-halt.md` for the full halt mechanism.
+
+## Examples
+
+```bash
+# Common: see what's available
+cross-agent-discover
+
+# Force fresh probe after network change
+cross-agent-discover --no-cache
+
+# What's on velox specifically
+cross-agent-discover --peer velox --enumerate-remote
+
+# Pipe to grep
+cross-agent-discover --json | jq '.peers[] | select(.reachable)'
+```
+
+## See also
+
+- `cross-agent-send` — uses `peers.toml` for routing destinations.
+- `cross-agent-status` — local pending messages.
+- `cross-agent-comms.org` — protocol spec, `* Limitations` section
+  explains the cross-machine model.