docs(rebrand): rewrite current docs for BCODE_*, bcode://, ~/.bcode

Updates observability, release, perf-benchmarks, quick-start, scripts,
KEYBINDINGS, and debugging rule docs to use the new env var names and
home directory. Adds an env var deprecation-window note at the top of
observability.md. Historical plans and specs are left untouched.

Author: Berkay2002

.claude/rules/debugging.md

@@ -19,7 +19,7 @@ The server writes structured NDJSON spans to a local trace file — always on du
 tail -f ./dev/logs/server.trace.ndjson
 
 # In production/CLI mode:
-tail -f ~/.t3/userdata/logs/server.trace.ndjson
+tail -f ~/.bcode/userdata/logs/server.trace.ndjson
 ```
 
 Read `@docs/observability.md` for the full set of jq queries. Key ones:

.docs/quick-start.md

@@ -8,7 +8,7 @@ bun run dev
 bun run dev:desktop
 
 # Desktop development on an isolated port set
-T3CODE_DEV_INSTANCE=feature-xyz bun run dev:desktop
+BCODE_DEV_INSTANCE=feature-xyz bun run dev:desktop
 
 # Production
 bun run build

.docs/scripts.md

@@ -3,7 +3,7 @@
 - `bun run dev` — Starts contracts, server, and web in `turbo watch` mode.
 - `bun run dev:server` — Starts just the WebSocket server (uses Bun TypeScript execution).
 - `bun run dev:web` — Starts just the Vite dev server for the web app.
-- Dev commands default `T3CODE_STATE_DIR` to `~/.t3/dev` to keep dev state isolated from desktop/prod state.
+- Dev commands default `BCODE_STATE_DIR` to `~/.bcode/dev` to keep dev state isolated from desktop/prod state.
 - Override server CLI-equivalent flags from root dev commands with `--`, for example:
   `bun run dev -- --base-dir ~/.t3-2`
 - `bun run start` — Runs the production server (serves built web app as static files).
@@ -33,10 +33,10 @@
 
 ## Running multiple dev instances
 
-Set `T3CODE_DEV_INSTANCE` to any value to deterministically shift all dev ports together.
+Set `BCODE_DEV_INSTANCE` to any value to deterministically shift all dev ports together.
 
 - Default ports: server `3773`, web `5733`
-- Shifted ports: `base + offset` (offset is hashed from `T3CODE_DEV_INSTANCE`)
-- Example: `T3CODE_DEV_INSTANCE=branch-a bun run dev:desktop`
+- Shifted ports: `base + offset` (offset is hashed from `BCODE_DEV_INSTANCE`)
+- Example: `BCODE_DEV_INSTANCE=branch-a bun run dev:desktop`
 
-If you want full control instead of hashing, set `T3CODE_PORT_OFFSET` to a numeric offset.
+If you want full control instead of hashing, set `BCODE_PORT_OFFSET` to a numeric offset.

KEYBINDINGS.md

@@ -2,7 +2,7 @@
 
 T3 Code reads keybindings from:
 
-- `~/.t3/keybindings.json`
+- `~/.bcode/keybindings.json`
 
 The file must be a JSON array of rules:
 

docs/observability.md

@@ -22,7 +22,7 @@ If you want a log message to show up in the trace file, emit it inside an active
 
 ### Traces
 
-Completed spans are written as NDJSON records to `serverTracePath` (by default, `~/.t3/userdata/logs/server.trace.ndjson`).
+Completed spans are written as NDJSON records to `serverTracePath` (by default, `~/.bcode/userdata/logs/server.trace.ndjson`).
 
 Important fields in each record:
 
@@ -58,6 +58,11 @@ There are two useful modes:
 
 The local trace file is always on. OTLP export is opt-in.
 
+> **Env var deprecation window (v0.0.19):** All `BCODE_*` env vars below are
+> also read from their legacy `T3CODE_*` names through v0.0.19, with a
+> one-time `[bcode]` console warning per legacy key. The `T3CODE_*` fallback
+> is removed in v0.0.20. Examples in this document use the new names.
+
 ### Option 1: Local Traces Only
 
 You do not need any extra env vars. Just run the app normally and inspect `server.trace.ndjson`.
@@ -99,16 +104,16 @@ Default Grafana login:
 #### 2. Export OTLP env vars
 
 ```bash
-export T3CODE_OTLP_TRACES_URL=http://localhost:4318/v1/traces
-export T3CODE_OTLP_METRICS_URL=http://localhost:4318/v1/metrics
-export T3CODE_OTLP_SERVICE_NAME=t3-local
+export BCODE_OTLP_TRACES_URL=http://localhost:4318/v1/traces
+export BCODE_OTLP_METRICS_URL=http://localhost:4318/v1/metrics
+export BCODE_OTLP_SERVICE_NAME=t3-local
 ```
 
 Optional:
 
 ```bash
-export T3CODE_TRACE_MIN_LEVEL=Info
-export T3CODE_TRACE_TIMING_ENABLED=true
+export BCODE_TRACE_MIN_LEVEL=Info
+export BCODE_TRACE_TIMING_ENABLED=true
 ```
 
 #### 3. Launch the app from that same shell
@@ -133,23 +138,23 @@ bun dev:desktop
 
 Packaged desktop app:
 
-Launch the actual app executable from the same shell so the desktop app and embedded backend inherit `T3CODE_OTLP_*`.
+Launch the actual app executable from the same shell so the desktop app and embedded backend inherit `BCODE_OTLP_*`.
 
 macOS app bundle example:
 
 ```bash
-T3CODE_OTLP_TRACES_URL=http://localhost:4318/v1/traces \
-T3CODE_OTLP_METRICS_URL=http://localhost:4318/v1/metrics \
-T3CODE_OTLP_SERVICE_NAME=t3-desktop \
+BCODE_OTLP_TRACES_URL=http://localhost:4318/v1/traces \
+BCODE_OTLP_METRICS_URL=http://localhost:4318/v1/metrics \
+BCODE_OTLP_SERVICE_NAME=t3-desktop \
 "/Applications/BCode (Alpha).app/Contents/MacOS/BCode (Alpha)"
 ```
 
 Direct binary example:
 
 ```bash
-T3CODE_OTLP_TRACES_URL=http://localhost:4318/v1/traces \
-T3CODE_OTLP_METRICS_URL=http://localhost:4318/v1/metrics \
-T3CODE_OTLP_SERVICE_NAME=t3-desktop \
+BCODE_OTLP_TRACES_URL=http://localhost:4318/v1/traces \
+BCODE_OTLP_METRICS_URL=http://localhost:4318/v1/metrics \
+BCODE_OTLP_SERVICE_NAME=t3-desktop \
 ./path/to/your/desktop-app-binary
 ```
 
@@ -168,7 +173,7 @@ The trace file is the fastest way to inspect raw span data.
 Tail it:
 
 ```bash
-tail -f "$T3CODE_HOME/userdata/logs/server.trace.ndjson"
+tail -f "$BCODE_HOME/userdata/logs/server.trace.ndjson"
 ```
 
 In monorepo dev, use:
@@ -185,7 +190,7 @@ jq -c 'select(.exit._tag != "Success") | {
   durationMs,
   exit,
   attributes
-}' "$T3CODE_HOME/userdata/logs/server.trace.ndjson"
+}' "$BCODE_HOME/userdata/logs/server.trace.ndjson"
 ```
 
 Show slow spans:
@@ -196,7 +201,7 @@ jq -c 'select(.durationMs > 1000) | {
   durationMs,
   traceId,
   spanId
-}' "$T3CODE_HOME/userdata/logs/server.trace.ndjson"
+}' "$BCODE_HOME/userdata/logs/server.trace.ndjson"
 ```
 
 Inspect embedded log events:
@@ -213,7 +218,7 @@ jq -c 'select(any(.events[]?; .attributes["effect.logLevel"] != null)) | {
         level: .attributes["effect.logLevel"]
       }
   ]
-}' "$T3CODE_HOME/userdata/logs/server.trace.ndjson"
+}' "$BCODE_HOME/userdata/logs/server.trace.ndjson"
 ```
 
 Follow one trace:
@@ -224,7 +229,7 @@ jq -r 'select(.traceId == "TRACE_ID_HERE") | [
   .spanId,
   (.parentSpanId // "-"),
   .durationMs
-] | @tsv' "$T3CODE_HOME/userdata/logs/server.trace.ndjson"
+] | @tsv' "$BCODE_HOME/userdata/logs/server.trace.ndjson"
 ```
 
 Filter orchestration commands:
@@ -235,7 +240,7 @@ jq -c 'select(.attributes["orchestration.command_type"] != null) | {
   durationMs,
   commandType: .attributes["orchestration.command_type"],
   aggregateKind: .attributes["orchestration.aggregate_kind"]
-}' "$T3CODE_HOME/userdata/logs/server.trace.ndjson"
+}' "$BCODE_HOME/userdata/logs/server.trace.ndjson"
 ```
 
 Filter git activity:
@@ -250,7 +255,7 @@ jq -c 'select(.attributes["git.operation"] != null) | {
     .events[]
     | select(.name == "git.hook.started" or .name == "git.hook.finished")
   ]
-}' "$T3CODE_HOME/userdata/logs/server.trace.ndjson"
+}' "$BCODE_HOME/userdata/logs/server.trace.ndjson"
 ```
 
 ### Use Tempo When You Need A Real Trace Viewer
@@ -358,7 +363,7 @@ If you need those later, add client-side instrumentation or a dedicated server f
 
 Usually one of these is true:
 
-- `T3CODE_OTLP_TRACES_URL` was not set
+- `BCODE_OTLP_TRACES_URL` was not set
 - the app was launched from a different environment than the one where you exported the vars
 - the app was not fully restarted after changing env
 - Grafana is looking at the wrong time range or service name
@@ -482,19 +487,19 @@ It provides:
 
 Local trace file:
 
-- `T3CODE_TRACE_FILE`: override trace file path
-- `T3CODE_TRACE_MAX_BYTES`: per-file rotation size, default `10485760`
-- `T3CODE_TRACE_MAX_FILES`: rotated file count, default `10`
-- `T3CODE_TRACE_BATCH_WINDOW_MS`: flush window, default `200`
-- `T3CODE_TRACE_MIN_LEVEL`: minimum trace level, default `Info`
-- `T3CODE_TRACE_TIMING_ENABLED`: enable timing metadata, default `true`
+- `BCODE_TRACE_FILE`: override trace file path
+- `BCODE_TRACE_MAX_BYTES`: per-file rotation size, default `10485760`
+- `BCODE_TRACE_MAX_FILES`: rotated file count, default `10`
+- `BCODE_TRACE_BATCH_WINDOW_MS`: flush window, default `200`
+- `BCODE_TRACE_MIN_LEVEL`: minimum trace level, default `Info`
+- `BCODE_TRACE_TIMING_ENABLED`: enable timing metadata, default `true`
 
 OTLP export:
 
-- `T3CODE_OTLP_TRACES_URL`: OTLP trace endpoint
-- `T3CODE_OTLP_METRICS_URL`: OTLP metric endpoint
-- `T3CODE_OTLP_EXPORT_INTERVAL_MS`: export interval, default `10000`
-- `T3CODE_OTLP_SERVICE_NAME`: service name, default `t3-server`
+- `BCODE_OTLP_TRACES_URL`: OTLP trace endpoint
+- `BCODE_OTLP_METRICS_URL`: OTLP metric endpoint
+- `BCODE_OTLP_EXPORT_INTERVAL_MS`: export interval, default `10000`
+- `BCODE_OTLP_SERVICE_NAME`: service name, default `t3-server`
 
 If the OTLP URLs are unset, local tracing still works and metrics stay in-process only.
 

docs/perf-benchmarks.md

@@ -164,14 +164,14 @@ bun run test:perf
 ### Watch the automated run in a live browser
 
 ```bash
-T3CODE_PERF_HEADFUL=1 bun run test:perf:web
+BCODE_PERF_HEADFUL=1 bun run test:perf:web
 ```
 
 If you already have fresh build artifacts:
 
 ```bash
 cd apps/web
-T3CODE_PERF_HEADFUL=1 bun run test:perf
+BCODE_PERF_HEADFUL=1 bun run test:perf
 ```
 
 ### Open the seeded app manually for exploration
@@ -241,20 +241,20 @@ Current summary fields:
 To change the artifact output directory for one run:
 
 ```bash
-T3CODE_PERF_ARTIFACT_DIR=/tmp/t3-perf bun run test:perf:web
+BCODE_PERF_ARTIFACT_DIR=/tmp/t3-perf bun run test:perf:web
 ```
 
 ## Internal env vars
 
 These are the perf-specific env vars in the current harness:
 
-- `T3CODE_PERF_HEADFUL=1`
+- `BCODE_PERF_HEADFUL=1`
   - Launch Chromium headed instead of headless.
-- `T3CODE_PERF_ARTIFACT_DIR=/path/to/output`
+- `BCODE_PERF_ARTIFACT_DIR=/path/to/output`
   - Override the artifact directory.
-- `T3CODE_PERF_PROVIDER=1`
+- `BCODE_PERF_PROVIDER=1`
   - Enables the perf provider path on the server.
-- `T3CODE_PERF_SCENARIO=dense_assistant_stream`
+- `BCODE_PERF_SCENARIO=dense_assistant_stream`
   - Selects the live perf provider scenario.
 
 In normal usage, the automated harness and `perf:open` script set the provider env vars for you.

docs/release.md

@@ -51,10 +51,10 @@ This document covers the unified release workflow for stable and nightly desktop
   - The desktop UI shows a rocket update button when an update is available; click once to download, click again after download to restart/install.
 - Provider: GitHub Releases (`provider: github`) configured at build time.
 - Repository slug source:
-  - `T3CODE_DESKTOP_UPDATE_REPOSITORY` (format `owner/repo`), if set.
+  - `BCODE_DESKTOP_UPDATE_REPOSITORY` (format `owner/repo`), if set.
   - otherwise `GITHUB_REPOSITORY` from GitHub Actions.
 - Temporary private-repo auth workaround:
-  - set `T3CODE_DESKTOP_UPDATE_GITHUB_TOKEN` (or `GH_TOKEN`) in the desktop app runtime environment.
+  - set `BCODE_DESKTOP_UPDATE_GITHUB_TOKEN` (or `GH_TOKEN`) in the desktop app runtime environment.
   - the app forwards it as an `Authorization: Bearer <token>` request header for updater HTTP calls.
 - Required release assets for updater:
   - platform installers (`.exe`, `.dmg`, `.AppImage`, plus macOS `.zip` for Squirrel.Mac update payloads)