Fixed and improved token tracking

docs/onboarding.md

@@ -0,0 +1,212 @@
+# State Hub Onboarding
+
+This guide turns a new machine into a usable State Hub operator or collaborator
+environment. It covers local credentials, SSH reachability, Gitea access, and
+Claude Code MCP registration.
+
+State Hub remains a coordination read/cache layer. Repo permissions, SSH
+access, and controlled tunnels are the first access boundary. OpenBao is the
+runtime secret authority for platform and workload secrets once its bootstrap
+ceremony is complete.
+
+## Quick Start
+
+Clone the repo, then run the bootstrap script:
+
+```bash
+git clone https://gitea.coulomb.social/coulomb/state-hub.git ~/state-hub
+cd ~/state-hub
+make bootstrap-env
+```
+
+On a clean Ubuntu 24.04 machine, allow package installation explicitly:
+
+```bash
+make bootstrap-env ARGS="--install-missing"
+```
+
+For a remote machine that reaches State Hub through ops-bridge:
+
+```bash
+make bridges
+make register-mcp MCP_URL=http://127.0.0.1:18001/sse API_BASE=http://127.0.0.1:18000
+```
+
+Restart Claude Code after MCP registration.
+
+## Primary Operator: New Machine
+
+1. Install minimal host prerequisites:
+
+   ```bash
+   sudo apt-get update
+   sudo apt-get install -y git curl openssh-client make python3
+   ```
+
+2. Clone `state-hub` and any domain repo you expect to operate:
+
+   ```bash
+   git clone https://gitea.coulomb.social/coulomb/state-hub.git ~/state-hub
+   git clone https://gitea.coulomb.social/coulomb/the-custodian.git ~/the-custodian
+   ```
+
+3. Run the bootstrap:
+
+   ```bash
+   cd ~/state-hub
+   make bootstrap-env ARGS="--install-missing"
+   ```
+
+   The script will:
+
+   - check required tools
+   - configure `git credential.helper`
+   - create `~/.ssh/id_ed25519` when missing
+   - print the public key for managed hosts
+   - create `~/.railiance_gitea.conf` when you provide a Gitea token
+   - register the State Hub MCP server for Claude Code
+   - check State Hub API reachability
+
+4. Authorize the SSH key on managed hosts. If password or existing key access
+   is available, rerun:
+
+   ```bash
+   make bootstrap-env ARGS="--authorize-ssh --skip-gitea --skip-mcp"
+   ```
+
+   Default targets:
+
+   - `tegwick@92.205.62.239` for Railiance01
+   - `tegwick@92.205.130.254` for CoulombCore
+
+5. Start or connect to State Hub:
+
+   ```bash
+   make api
+   make mcp-http
+   ```
+
+   If the hub is remote, use ops-bridge:
+
+   ```bash
+   make bridges
+   ```
+
+6. Restart Claude Code and verify that `state-hub` appears in the MCP server
+   list. In the first session, call `get_state_summary()` when MCP tools are
+   available. If not, use:
+
+   ```bash
+   cat .custodian-brief.md
+   curl -s "http://127.0.0.1:8000/workstreams/?status=active" | python3 -m json.tool
+   ```
+
+## Domain Collaborator: New Person
+
+1. Get a Gitea account with write access to the relevant domain repo.
+2. Clone this repo and the domain repo:
+
+   ```bash
+   git clone https://gitea.coulomb.social/coulomb/state-hub.git ~/state-hub
+   git clone https://gitea.coulomb.social/coulomb/<domain-repo>.git ~/<domain-repo>
+   ```
+
+3. Run the bootstrap:
+
+   ```bash
+   cd ~/state-hub
+   make bootstrap-env
+   ```
+
+4. Send the printed SSH public key to the operator, or authorize it yourself if
+   you already have host access:
+
+   ```bash
+   ssh-copy-id -i ~/.ssh/id_ed25519.pub tegwick@92.205.62.239
+   ```
+
+5. Bring up the State Hub tunnel when direct local access is unavailable:
+
+   ```bash
+   make bridges
+   make register-mcp MCP_URL=http://127.0.0.1:18001/sse API_BASE=http://127.0.0.1:18000
+   ```
+
+6. Restart Claude Code, open the domain repo, and orient from the repo brief:
+
+   ```bash
+   cat .custodian-brief.md
+   ```
+
+7. Contribute work through repo-backed workplans. A new workplan lives under
+   `workplans/` and follows ADR-001. The hub indexes files; the files remain
+   authoritative.
+
+## Credential Helper Choices
+
+`make bootstrap-env` configures Git credentials only when no global helper is
+already set.
+
+Default behavior:
+
+- use `libsecret` when the helper exists
+- otherwise use `credential.helper=cache --timeout=3600`
+
+For headless hosts where a persistent plaintext helper is acceptable:
+
+```bash
+make bootstrap-env ARGS="--git-helper store --allow-plaintext-store"
+```
+
+Prefer SSH remotes or a keyring-backed helper for normal operator machines.
+
+## Gitea Token File
+
+Some Railiance scripts read `~/.railiance_gitea.conf`:
+
+```bash
+GITEA_URL="http://92.205.130.254:32166"
+GITEA_USER="<user>"
+GITEA_TOKEN="<token>"
+```
+
+Required token capabilities depend on the action:
+
+- repo creation needs `read:user` and repository write/admin scope
+- package publishing needs package write scope
+- inventory reads need repository read scope
+
+The bootstrap script writes this file with mode `0600` and does not print the
+token.
+
+## MCP Registration
+
+Local registration:
+
+```bash
+make register-mcp
+```
+
+Tunnel registration:
+
+```bash
+make register-mcp MCP_URL=http://127.0.0.1:18001/sse API_BASE=http://127.0.0.1:18000
+```
+
+The current State Hub MCP transport is SSE. The old `.mcp.json`/stdio flow is
+legacy; use `make mcp-http` to run the SSE service on `127.0.0.1:8001`.
+
+## Verification Checklist
+
+Run these checks after bootstrap:
+
+```bash
+git config --global --get credential.helper
+test -f ~/.ssh/id_ed25519.pub
+test -f ~/.railiance_gitea.conf
+curl -fsS http://127.0.0.1:8000/state/health || curl -fsS http://127.0.0.1:18000/state/health
+make register-mcp DRY_RUN=1
+```
+
+Then restart Claude Code and confirm that the `state-hub` MCP server is
+available.