create-byan-agent 2.26.0 → 2.27.0

package/install/templates/_byan/mcp/byan-mcp-server/skill-bundles-manifest.json

@@ -0,0 +1,268 @@
+{
+  "skills": {
+    "byan-benchmark": {
+      "name": "byan-benchmark",
+      "module": "core",
+      "tier": "connector-bound",
+      "sourceHash": "65c7e7a7a1120bd4c9fadf7a801702d7350755a35936a1c9a8525074f313889e"
+    },
+    "byan-bmad-agent-tao": {
+      "name": "byan-bmad-agent-tao",
+      "module": "core",
+      "tier": "standalone",
+      "sourceHash": "0ea734ea8af452a70f8ebfc242da09db22ad1d4cb308dc71634843d5cf8ff7ea"
+    },
+    "byan-bmad-master": {
+      "name": "byan-bmad-master",
+      "module": "core",
+      "tier": "standalone",
+      "sourceHash": "6392479868942113f818f4042cc4a08d7208e96f984c8b6e41f23bd8b9191e20"
+    },
+    "byan-bmb-agent-builder": {
+      "name": "byan-bmb-agent-builder",
+      "module": "bmb",
+      "tier": "standalone",
+      "sourceHash": "ac3dd636e6a725b486543d118f2f9fd5b0dd290610dca30b84eb950dc510cf6f"
+    },
+    "byan-bmb-module-builder": {
+      "name": "byan-bmb-module-builder",
+      "module": "bmb",
+      "tier": "standalone",
+      "sourceHash": "f87f85619d6f9496ecddbe35a57259405988f5aa610dd784617f9a0295d93e12"
+    },
+    "byan-bmb-workflow-builder": {
+      "name": "byan-bmb-workflow-builder",
+      "module": "bmb",
+      "tier": "standalone",
+      "sourceHash": "cf0f6bda49852fbdb934c32063f3f39b1d524bd2a92ced8bf516371f0be80076"
+    },
+    "byan-bmm-analyst": {
+      "name": "byan-bmm-analyst",
+      "module": "bmm",
+      "tier": "standalone",
+      "sourceHash": "e3fdfefdf459aea17344b92393d25be3d177b972fadbc43767806f7b6d2d5f58"
+    },
+    "byan-bmm-architect": {
+      "name": "byan-bmm-architect",
+      "module": "bmm",
+      "tier": "standalone",
+      "sourceHash": "4629b9c9efb538eca74174fcaafce40996c075c0be8493abd61eb8fb257a8250"
+    },
+    "byan-bmm-dev": {
+      "name": "byan-bmm-dev",
+      "module": "bmm",
+      "tier": "standalone",
+      "sourceHash": "bc05f82e1ea4aa0b6725236f9f399baaad016ea21f660649a3e0035ba9bdb5d8"
+    },
+    "byan-bmm-pm": {
+      "name": "byan-bmm-pm",
+      "module": "bmm",
+      "tier": "standalone",
+      "sourceHash": "5f742730d9076dd5dded56f36a51c586c175918cf6e42d88dc44e6e924058a8d"
+    },
+    "byan-bmm-quick-flow-solo-dev": {
+      "name": "byan-bmm-quick-flow-solo-dev",
+      "module": "bmm",
+      "tier": "standalone",
+      "sourceHash": "de7e0c1078869f21aff4f603ef8d712ebf00cabdf4b6c5aad1adc773cabb24ad"
+    },
+    "byan-bmm-quinn": {
+      "name": "byan-bmm-quinn",
+      "module": "bmm",
+      "tier": "standalone",
+      "sourceHash": "0015623824cfd26280da3ba35d2f24c921137f345ad4078ccbe3c315aee9301c"
+    },
+    "byan-bmm-sm": {
+      "name": "byan-bmm-sm",
+      "module": "bmm",
+      "tier": "standalone",
+      "sourceHash": "6d9d3ed392da60ff78bfb633b1a51284977ecb055b025aa2de0717e9fb268d00"
+    },
+    "byan-bmm-tech-writer": {
+      "name": "byan-bmm-tech-writer",
+      "module": "bmm",
+      "tier": "standalone",
+      "sourceHash": "8d52f744ea00323434d3841d875a94882961e6870f257c29c2c083b8cf2c58dd"
+    },
+    "byan-bmm-ux-designer": {
+      "name": "byan-bmm-ux-designer",
+      "module": "bmm",
+      "tier": "standalone",
+      "sourceHash": "f02a086944037e585ed187801d6fbfc2aa493747db0b5a2cb7c611342be387f1"
+    },
+    "byan-byan": {
+      "name": "byan-byan",
+      "module": "core",
+      "tier": "connector-bound",
+      "sourceHash": "0a1f4b1333f7f42a43b1a8ad57b0d7d687aec95f149ae13ba98b78970ed3bd09"
+    },
+    "byan-byan-v2": {
+      "name": "byan-byan-v2",
+      "module": "core",
+      "tier": "standalone",
+      "sourceHash": "ff3b2aef3562eaf3e611637f2ea6c3a4ca540f9ada955f475aff25f70408287a"
+    },
+    "byan-carmack": {
+      "name": "byan-carmack",
+      "module": "core",
+      "tier": "standalone",
+      "sourceHash": "f4a3e474417483a1f924bfd69dbcf14a7209c5284530cb013186b850154bc54b"
+    },
+    "byan-cis-brainstorming-coach": {
+      "name": "byan-cis-brainstorming-coach",
+      "module": "cis",
+      "tier": "standalone",
+      "sourceHash": "1c5450b1cb68bdeb8e23ac2d906cb0310adedb58441725e8c6370f16ced1c2e4"
+    },
+    "byan-cis-creative-problem-solver": {
+      "name": "byan-cis-creative-problem-solver",
+      "module": "cis",
+      "tier": "standalone",
+      "sourceHash": "a72dd267964c7f0ecb3274b75bc11dd4ec548ec6d193254ad1a4f9b913136fdb"
+    },
+    "byan-cis-design-thinking-coach": {
+      "name": "byan-cis-design-thinking-coach",
+      "module": "cis",
+      "tier": "standalone",
+      "sourceHash": "4244966a9d3f1fe135a9f46a08ea6301ba6c760933ad24642bc800b75dcb1380"
+    },
+    "byan-cis-innovation-strategist": {
+      "name": "byan-cis-innovation-strategist",
+      "module": "cis",
+      "tier": "standalone",
+      "sourceHash": "3b8afbc5944d3300b86a438af069477a69edff307c547c1ba5c17c6e6ac905aa"
+    },
+    "byan-cis-presentation-master": {
+      "name": "byan-cis-presentation-master",
+      "module": "cis",
+      "tier": "standalone",
+      "sourceHash": "7b7390d6b7e54d32c6daaeb8a55a8ba0f683f1e98835f59d0092e3c45abe1e4a"
+    },
+    "byan-cis-storyteller": {
+      "name": "byan-cis-storyteller",
+      "module": "cis",
+      "tier": "standalone",
+      "sourceHash": "8b5ac44272e05323d7c5be8d259359e708b298f201919878df98699b51bdda36"
+    },
+    "byan-claude": {
+      "name": "byan-claude",
+      "module": "core",
+      "tier": "standalone",
+      "sourceHash": "e8a31ac880148685805ae98576f0d1a167e577f62b259ff8d7b8f0eaba711772"
+    },
+    "byan-codex": {
+      "name": "byan-codex",
+      "module": "core",
+      "tier": "standalone",
+      "sourceHash": "0f0d7a1108a43a0c0c8093cc5600bc2649d6766c6ae94c2a2a9dafa315180627"
+    },
+    "byan-drawio": {
+      "name": "byan-drawio",
+      "module": "bmb",
+      "tier": "standalone",
+      "sourceHash": "ff771c02bcdac126dcae9d8dc6d8692625bed93778782de303c6bd3ebd57a76b"
+    },
+    "byan-elo-trust": {
+      "name": "byan-elo-trust",
+      "module": "core",
+      "tier": "standalone",
+      "sourceHash": "64917fa7dc10362b08e0d846e09d610960b871590e8cdd490f143346a24fe8f4"
+    },
+    "byan-fact-check": {
+      "name": "byan-fact-check",
+      "module": "core",
+      "tier": "standalone",
+      "sourceHash": "0ab47ccc715638b516dc57a7b006ee4be93d0158121d6075152ed64ace1c0a3b"
+    },
+    "byan-forge": {
+      "name": "byan-forge",
+      "module": "core",
+      "tier": "standalone",
+      "sourceHash": "9c4f1fffd4d32d5c2b87fb62eeba7dfbaf0c77d810028a16a54dc5e8d4c0061d"
+    },
+    "byan-hermes-dispatch": {
+      "name": "byan-hermes-dispatch",
+      "module": "core",
+      "tier": "connector-bound",
+      "sourceHash": "62b9c959c77468c0e14e3dfd45039151d29b1bcdc18b04b4d0deac606052a976"
+    },
+    "byan-insight": {
+      "name": "byan-insight",
+      "module": "core",
+      "tier": "connector-bound",
+      "sourceHash": "188e4b0cd1791a01c1edf6d94e65f91d80d1fa1d522fa1de46259420cf348783"
+    },
+    "byan-mantra-audit": {
+      "name": "byan-mantra-audit",
+      "module": "core",
+      "tier": "standalone",
+      "sourceHash": "eab42571d276fa0b2ccaacb47a8bbb5c467168dab744ef9dc54cd684ca7724da"
+    },
+    "byan-merise-agile": {
+      "name": "byan-merise-agile",
+      "module": "core",
+      "tier": "standalone",
+      "sourceHash": "c0af31451bd3127772d04acf51df00d3ee2c28c47130043d87e6a4414b4a22f5"
+    },
+    "byan-native-dev-story": {
+      "name": "byan-native-dev-story",
+      "module": "core",
+      "tier": "connector-bound",
+      "sourceHash": "441cc28084d0520372772e41755535cf2126e0faf5d747ab888556bb9bcf81ec"
+    },
+    "byan-orchestrate": {
+      "name": "byan-orchestrate",
+      "module": "core",
+      "tier": "connector-bound",
+      "sourceHash": "2ee08e3f447cd25c5aafc45271f7ac518d09e380daeae3a71f9fbf2dc2e0d3e5"
+    },
+    "byan-patnote": {
+      "name": "byan-patnote",
+      "module": "core",
+      "tier": "standalone",
+      "sourceHash": "0d6beab6b70fd8107dd4e576caed6329c760f24489286079532c6b95e7657f68"
+    },
+    "byan-project": {
+      "name": "byan-project",
+      "module": "core",
+      "tier": "connector-bound",
+      "sourceHash": "0c835749db5d915b29a1d7c7b037d249073ce43c02f5e6d3daf84bdea678ee98"
+    },
+    "byan-rachid": {
+      "name": "byan-rachid",
+      "module": "core",
+      "tier": "standalone",
+      "sourceHash": "be1483991a1971915a3c641cc260bf808585682f513386c95aa709a5d90ec5b6"
+    },
+    "byan-skeptic": {
+      "name": "byan-skeptic",
+      "module": "core",
+      "tier": "standalone",
+      "sourceHash": "6592f44e636d761f0d81369f1d72ad00db6abc0c0dccb3fab23e9f92ba7ffe76"
+    },
+    "byan-strict": {
+      "name": "byan-strict",
+      "module": "core",
+      "tier": "connector-bound",
+      "sourceHash": "e8e0ac502220056a5057d2801ad5a512ce2bc7e54c08d9bc1844419d93ff58a6"
+    },
+    "byan-suitability": {
+      "name": "byan-suitability",
+      "module": "core",
+      "tier": "connector-bound",
+      "sourceHash": "ade5a0937ff3d7095753fa7cb9491d5f4579712a470010f84c1ac257fac0d70c"
+    },
+    "byan-tea-tea": {
+      "name": "byan-tea-tea",
+      "module": "tea",
+      "tier": "standalone",
+      "sourceHash": "d5ded39d2ede5f71bf51eff76b5c0fb1052d766122d1f378d2b1f6696109ed97"
+    },
+    "byan-yanstaller": {
+      "name": "byan-yanstaller",
+      "module": "core",
+      "tier": "standalone",
+      "sourceHash": "6ef12d7083c4e6b00cb9ce335c0494ef1b0faa2fe6d6cbc1f6fc09493bce611f"
+    }
+  }
+}

package/install/templates/docs/connector-admin-runbook.md

@@ -0,0 +1,279 @@
+# BYAN remote connector — admin runbook (Claude Team)
+
+> Goal: make BYAN available to a whole Claude Team org via a remote MCP Org
+> Connector, plus org-published skills. This runbook covers the in-repo
+> enabling layer (shipped) and the hosting + enrollment layer now built in
+> byan_web (F8).
+
+> Status as of F8: the sidecar image, the Traefik route, and the per-member
+> enrollment endpoint are all built. The remaining steps require a human at a
+> terminal (DNS, docker build, docker compose up) or on Claude.ai (register
+> the connector). Those gaps are called out explicitly -- they are not silent
+> cuts.
+
+## Two surfaces, one connector
+
+Claude Team has two distinct surfaces:
+
+- **Claude.ai Team** (web/desktop): seats, Projects, Artifacts, Org Connectors,
+  org-published Skills. A local stdio MCP server does not work here — a **remote**
+  MCP endpoint (HTTP/SSE) added as an Org Connector is required.
+- **Claude Code** (CLI/IDE): reads a per-repo `.claude/` config; an org connector
+  added on Claude.ai also syncs down to Claude Code.
+
+The remote connector is the spine: one endpoint serves both surfaces.
+
+## What ships in this repo (the enabling layer)
+
+- `server.js` — `createByanServer({ token, remoteOnly })` factory. The stdio path
+  (`node server.js`) is unchanged.
+- `server-http.js` — a stateless streamable-HTTP transport on `POST/GET /mcp`
+  (plus `/health`). The streamable-HTTP transport carries the SSE streaming leg
+  itself, so no separate legacy `/sse` endpoint is mounted.
+- Per-request identity: the caller's token is read from each request's
+  `Authorization` header and threaded through the byan_web calls, so two members
+  on the shared endpoint reach byan_web with their own token (not a shared one).
+- Remote-safe surface: `remoteOnly` exposes only `REMOTE_SAFE_TOOLS` — a
+  read-only, byan_web-backed allowlist (`byan_ping`, `byan_list_projects`, the
+  read `byan_api_*` tools). Stateful / filesystem-local / write tools stay
+  stdio-only and are refused on the remote transport. The `byan-lint-remote-safe`
+  check guards the allowlist.
+- Skill bundles: `bin/byan-build-skill-bundles.js` emits one `.zip` per skill into
+  `dist/skill-bundles/` — each archive is a single top-level folder + its SKILL.md,
+  the exact shape Claude.ai org Skills requires (it rejects a flat SKILL.md and
+  rejects a multi-skill archive, so there is no megabundle upload). The tracked
+  drift ledger is `skill-bundles-manifest.json` (`--check`).
+
+## Local run (verify the endpoint)
+
+```
+node _byan/mcp/byan-mcp-server/server-http.js
+# listens on :8848/mcp (override with BYAN_MCP_HTTP_PORT / BYAN_MCP_HTTP_PATH)
+curl -s localhost:8848/health
+```
+
+## Hosting — byan_web sidecar (BUILT, F8)
+
+The hosting track previously listed as a cross-repo dependency is now built.
+Below is what was added and how it is structured.
+
+### Image
+
+The connector runs as a Docker sidecar image built from
+`~/BYAN/_byan/mcp/byan-mcp-server/Dockerfile` (node:22-slim + tini PID1,
+`npm ci --omit=dev`, `CMD node server-http.js`). The image listens on `:8848`.
+
+Anti-vendoring boundary: `byan_web` references the image by tag but does NOT
+build it. The build is the operator's responsibility on the deploy host.
+
+    # Run once on the deploy host before `docker compose up`
+    docker build -t byan-mcp-connector:latest /home/yan/BYAN/_byan/mcp/byan-mcp-server
+
+Note: the `:latest` tag is used in the current compose file. A pinned immutable
+tag (e.g. `byan-mcp-connector:2.28.0`) is deferred to F11.
+
+### Compose service
+
+`byan-mcp-connector` is declared in
+`byan_web/api/docker-compose.byan-api.yml`. Key properties:
+
+- `BYAN_API_URL=http://byan-api:3737` — loopback DNS on the Docker user-defined
+  network (`proxy` / `admin_proxy`); no traversal through Traefik.
+- `BYAN_MCP_HTTP_PORT=8848`
+- No `BYAN_API_TOKEN` in the environment (enforced by `assertNoAmbientToken` at
+  boot — see Security invariants below).
+- `depends_on: byan-api: condition: service_healthy`
+- Healthcheck: `wget -qO- http://127.0.0.1:8848/health`
+
+### Traefik route
+
+Router `byan-mcp-secure` maps `byan-mcp.<domain>` to port 8848:
+
+- Entrypoint: `websecure`
+- TLS: `certresolver=letsencrypt`
+- Middleware: `byan-strip-trust@docker` (strips `X-Byan-Sso-Trust` and
+  `X-Authentik-Username` injected upstream by Authentik)
+- No `forwardauth` Authentik middleware — the connector authenticates via the
+  per-request `Authorization` header, not the SSO session
+
+The `BYAN_MCP_HOST` env var overrides the subdomain prefix (default: `byan-mcp`).
+
+---
+
+## Per-member enrollment (BUILT, F8)
+
+### Endpoint
+
+`POST /api/connector/link` — declared in
+`byan_web/api/routes/connector-link.js`, guarded by `authRequired`.
+
+Behavior:
+
+- First call: mints a personal `byan_` API key (`name='claude-connector'`,
+  `scopes=['connector:read']`). The raw key is returned exactly once in the
+  `201` response under `data.key`. The key hash is stored (sha256-at-rest); the
+  raw value is never persisted.
+- Subsequent calls (idempotent): returns `{ linked: true, keyId, last_used_at }`
+  — no re-mint, raw key not re-exposed.
+- Self-scoped: `body.userId` / `body.user_id` are ignored; the key always belongs
+  to the authenticated caller.
+- Bounded TTL: the minted key carries a 90-day `expires_at`. After expiry, the
+  next `POST /api/connector/link` transparently mints a fresh key (the member
+  re-runs enrollment). This bounds the blast radius of a leaked key.
+
+### Enrollment steps for one member
+
+1. The member logs in to `byan.<domain>` via Authentik SSO (they need an
+   existing byan_web account).
+2. The member calls `POST /api/connector/link` (any authenticated HTTP client,
+   or the byan_web UI if wired). The response contains the raw key under
+   `data.key` -- copy it immediately; it is not shown again.
+3. The member adds the remote connector in Claude.ai:
+   - Claude.ai -> Organization settings -> Connectors -> Add custom connector
+   - URL: `https://byan-mcp.<domain>/mcp`
+   - Authorization header: `ApiKey byan_xxxxxxxx` (paste the key from step 2)
+4. Verify: send `byan_ping` and `byan_list_projects` from Claude.ai. Both should
+   return data scoped to that member's account only.
+
+An unlinked member (no `Authorization` header, or an invalid token) receives a
+degraded response -- "link your byan_web account" -- never a default identity.
+
+---
+
+## Pilot procedure (1 member, before org-wide rollout)
+
+Run this before publishing the connector to the entire org.
+
+1. Deploy the sidecar on the byan_web host (operator step -- see gaps below).
+2. One pilot member follows the enrollment steps above.
+3. Verify isolation: confirm `byan_ping` and `byan_list_projects` return only
+   that member's projects, not projects belonging to other users.
+4. Monitor `api_keys.last_used_at` for the pilot key for 48 hours. Check for
+   unexpected call volume or error patterns in the byan_web API logs.
+5. Only after 48 hours of clean pilot: register the connector as an org-wide
+   connector on Claude.ai and communicate the enrollment URL to all members.
+
+If any isolation issue is found in step 3, stop. Do not proceed to org-wide
+rollout until the issue is diagnosed and fixed.
+
+---
+
+## Security invariants
+
+These are enforced in code and must remain true after any future change:
+
+- **No ambient token on the sidecar.** `assertNoAmbientToken` in `server-http.js`
+  throws at boot if `BYAN_API_TOKEN` is present in the process environment. A
+  deploy that accidentally sets this variable will fail loudly, not silently
+  collapse all callers onto one identity. The compose service deliberately omits
+  this variable.
+- **Per-request identity only.** `resolveCallerToken` in `remoteOnly` mode never
+  falls back to `process.env.BYAN_API_TOKEN`. Two concurrent Team members hitting
+  the same endpoint use their own tokens, not a shared one.
+- **Read-only remote surface.** `remoteOnly: true` constrains the exposed tools to
+  `REMOTE_SAFE_TOOLS` — a read-only, byan_web-backed allowlist. Stateful,
+  filesystem-local, and write tools are refused on the remote transport.
+- **No Authentik identity headers.** The connector does not read `x-authentik-*`
+  headers for identity. `byan-strip-trust` strips `X-Byan-Sso-Trust` and
+  `X-Authentik-Username`; the remaining `x-authentik-*` headers are not stripped
+  by the middleware. The security guarantee comes from the connector never reading
+  them -- the applicative invariant is the real gate.
+- **Key hash only.** The raw `byan_` key is never stored. Only the sha256 hash is
+  persisted. The raw key is returned once at mint time and is unrecoverable after
+  that.
+- **The connector key is full-capability -- treat it as a secret.** byan_web does
+  not yet enforce `api_key` scopes server-side, so `scopes=['connector:read']` is a
+  forward-looking label, not an enforced limit. The minted key is a full read/write
+  byan_web user key; its read-only behaviour is enforced only at the MCP transport
+  (`REMOTE_SAFE_TOOLS`), not at the credential. A holder of the raw key could call
+  byan_web directly (e.g. `curl`) with the member's full privileges, bypassing the
+  transport allowlist. Mitigations in place: a 90-day TTL (`expires_at`) bounds the
+  exposure window, and the key is revocable via `DELETE /api/auth/api-keys/:id`.
+  Because the key lives in the Claude.ai connector config (a third-party surface),
+  members must treat it as a sensitive secret. Enforcing the scope server-side is a
+  follow-up (a cross-cutting RBAC change, deliberately out of this scope).
+
+---
+
+## Revocation
+
+Revoke a connector key via `DELETE /api/auth/api-keys/:id` (user-scoped,
+authenticated). This is the existing key-management endpoint.
+
+Note: `api_keys` has no `active` column. Revocation is by `expires_at` or
+`DELETE` -- there is no soft-disable flag. A named wrapper endpoint
+`DELETE /api/connector/link` is deferred to F9.
+
+Backstop: every connector key auto-expires after 90 days (the mint-time
+`expires_at` TTL). A forgotten or leaked key therefore cannot be used
+indefinitely; the member simply re-runs enrollment to mint a fresh one.
+
+---
+
+## What is deferred
+
+- **OAuth flow.** The current enrollment is key-paste. An OAuth authorize/token/
+  PKCE flow is deferred. Before building it, reconfirm against the current
+  Claude.ai documentation that Team org connectors accept a per-request API key
+  (not only OAuth tokens) -- do not build OAuth on an assumption.
+- **Pinned image tag.** The compose file uses `byan-mcp-connector:latest`. A
+  pinned immutable tag is deferred to F11.
+- **DELETE /api/connector/link wrapper.** Deferred to F9.
+
+---
+
+## Operator gaps (not automatable by the agent)
+
+The following steps cannot be performed by the agent. They require a human at a
+terminal or on Claude.ai:
+
+1. Create the DNS record `byan-mcp.<domain>` pointing to the byan_web host.
+2. On the deploy host, build and tag the sidecar image:
+   `docker build -t byan-mcp-connector:latest /home/yan/BYAN/_byan/mcp/byan-mcp-server`
+3. Bring the sidecar up:
+   `docker compose -f api/docker-compose.byan-api.yml up -d byan-mcp-connector`
+4. Register the connector on Claude.ai (Organization settings -> Connectors).
+5. Run the 48-hour pilot and confirm isolation before org-wide rollout.
+6. Push branches and PRs (the server cannot push to GitHub -- ask the operator).
+
+---
+
+## Admin steps (org-wide, after pilot)
+
+1. **Add the connector**: Claude.ai -> Organization settings -> Connectors ->
+   add the custom remote MCP connector pointing at `https://byan-mcp.<domain>/mcp`.
+2. **Members enroll**: each member follows the per-member enrollment steps above
+   (log in, POST /api/connector/link, paste key into the connector config).
+   An unlinked member is degraded gracefully, never assigned a default identity.
+3. **Publish skills**: run `node _byan/mcp/byan-mcp-server/bin/byan-build-skill-bundles.js`,
+   then upload each per-skill `.zip` from `dist/skill-bundles/` to Claude.ai ->
+   Organization settings -> Skills, ONE archive at a time (Claude accepts one skill
+   per `.zip` = one top-level folder + SKILL.md; a multi-skill archive is rejected).
+   Skills are static snapshots, so re-upload after a skill changes (the pre-commit
+   drift gate keeps the repo side
+   honest).
+
+## The two auth channels — do not cross them
+
+| Channel | Where the token lives | Used by |
+|---------|-----------------------|---------|
+| Connector (remote) | per-request `Authorization` header (`ApiKey byan_xxxxxxxx`, per-member key from `/api/connector/link`; OAuth deferred) | Claude.ai Team web + Claude Code via the org connector |
+| Local (`${BYAN_API_TOKEN}`) | `.claude/settings.local.json` / `.env` (gitignored) | the local stdio server (`node server.js`) for a single developer |
+
+These are separate paths. The local env token is the single-developer fallback;
+the connector identity is per-member. Mixing them (e.g. a shared service token on
+the connector) would collapse members onto one identity — which is why the
+per-request path exists.
+
+## Scope note (state on Claude.ai)
+
+Claude.ai Projects and Artifacts have no external API, so BYAN state is not
+synced into them. byan_web stays the authority for FD / strict / project state;
+the connector exposes that state live in-chat. A manual `byan_insight_digest`
+export can be pasted into a Project knowledge base when a frozen snapshot is
+wanted.
+
+## See also
+
+- `.claude/rules/byan-api.md` — the byan_web API + MCP tool families.
+- `docs/leantime-integration.md` — the Leantime board sync (separate backend).

package/install/templates/docs/leantime-integration.md

@@ -87,6 +87,27 @@ server after editing `settings.local.json`.
 When the pair is absent, the `byan_leantime_*` tools report `enabled: false` and
 the FD proceeds unchanged.
 
+### Configuring via the installer (interactive)
+
+`npx create-byan-agent` offers an opt-in Leantime block (after the byan_web
+step, Claude Code targets only). It defaults to **no**; when accepted it asks
+for the backend URL (with the wrong-host warning), the `lt_` API key (masked),
+and an optional user id, then:
+
+- writes `LEANTIME_API_URL` / `LEANTIME_API_TOKEN` (+ `LEANTIME_ASSIGN_USER_ID`
+  when given) into `.claude/settings.local.json` and `.env` (both gitignored);
+- adds the `${LEANTIME_API_URL}` / `${LEANTIME_API_TOKEN}` references to the
+  `byan` entry in `.mcp.json` (references only — the secret value stays out of
+  tracked files: `settings.local.json` and `.env` are gitignored, `.mcp.json`
+  holds only the `${...}` placeholders);
+- runs a reachability probe that flags the wrong-host case (`non_json`) on the
+  spot.
+
+The token is **per-instance**: each user points at their own Leantime with their
+own key, so the key is not shared across installs. Declining the prompt writes
+nothing. The manual `settings.local.json` path above remains valid (and is what
+the installer automates).
+
 ## Generating the Leantime API key
 
 Verified against Leantime source (3.7.x). Two credential types, both sent as the

package/node_modules/byan-platform-config/README.md

@@ -22,6 +22,7 @@ const {
   tokenPrompt,
   validate,
   urlUtils,
+  credentials,
 } = require('byan-platform-config');
 ```
 
@@ -92,6 +93,27 @@ urlUtils.buildAuthHeader('byan_abc');       // → { Authorization: 'ApiKey byan
 urlUtils.buildAuthHeader('eyJ...');         // → { Authorization: 'Bearer eyJ...' }
 ```
 
+### credentials — global `~/.byan/credentials.json`
+
+The byan MCP server resolves its own config (`BYAN_API_URL`, `BYAN_API_TOKEN`,
+`LEANTIME_API_URL`, `LEANTIME_API_TOKEN`) at boot. `credentials.writeCredentials`
+persists those to a global, per-user, gitignored, chmod-600 file so the config
+is portable across shells (zsh/fish/bash) and OSes (`os.homedir()` resolves `~`
+on Unix and `%USERPROFILE%` on Windows) and reaches Claude Code AND Codex —
+without depending on `.mcp.json` `${...}` expansion.
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `writeCredentials` | `(values, { homedir? }) -> { path, written }` | merge-write the known keys; created at mode 0600; idempotent; ignores `${...}`/empty |
+| `readCredentials` | `(homedir?) -> object` | `{}` on a missing/invalid file (does not throw) |
+| `credentialsPath` | `(homedir?) -> string` | `<homedir>/.byan/credentials.json` |
+
+**Resolution precedence (server side):** `process.env` (a real value; an
+unexpanded `${...}` is treated as absent) `->` `~/.byan/credentials.json` `->`
+`http://localhost:3737`. A real `BYAN_API_URL` env var therefore still wins
+(prod sidecar / Docker / CI), the global file is the local-dev fallback, and the
+token is kept out of `.mcp.json`.
+
 ## Test
 
 ```bash
@@ -101,7 +123,8 @@ npm test
 ## Design invariants
 
 - READ-MERGE-WRITE on every file operation — unknown keys are preserved.
-- `ensureMcpConfig` keeps `mcpServers.byan.command` and `.args` if already set.
+- `ensureMcpConfig` keeps `mcpServers.byan.command` and `.args` if already set; it writes NO byan config env (the server resolves its own).
+- `writeCredentials` creates the file at mode 0600 (no group/other read window) and is a no-op-safe merge.
 - `validateByanWebReachability` resolves instead of rejecting — errors surface in the result object.
 - `stripApiSuffix` is idempotent and leaves URLs without a `/api` suffix untouched.
 - `buildAuthHeader` returns `{}` (not `{ Authorization: undefined }`) when token is missing.

package/node_modules/byan-platform-config/index.js

@@ -13,4 +13,5 @@ module.exports = {
   tokenPrompt: require('./lib/token-prompt'),
   validate: require('./lib/validate'),
   urlUtils: require('./lib/url-utils'),
+  credentials: require('./lib/credentials'),
 };