Clean up UI/data boundary around app-level contract

AGENTS.md

@@ -43,6 +43,8 @@ Typical workflow:
 
 The dev frontend talks to the **production backend** (see `VITE_VIBENOTE_API_BASE` in `.env`), so e2e tests exercise real API flows — shares get committed to GitHub, sync hits the real server, etc.
 
+For large-scale UI/data-hook refactors, a generic "open the changed UI" check is not enough. Run the dedicated smoke checklist in `docs/browser-smoke.md` and record what you exercised.
+
 ### Commit Conventions
 
 - Do NOT commit unless asked. Even if you were asked to commit within a session, don't commit more changes in the same session without being asked.

docs/browser-smoke.md

@@ -0,0 +1,57 @@
+# Browser Smoke
+
+Manual browser smoke checks for changes that affect app wiring, routing, repo state, or large UI/data-hook refactors.
+
+Use this alongside the `agent-browser` workflow in `AGENTS.md`.
+
+## When To Run This
+
+Run this checklist when a change touches any of:
+
+- `src/App.tsx`
+- `src/data.ts`
+- shared routing/state contracts
+- repo switching
+- file tree selection / navigation sync
+- large refactors that should preserve existing UI behavior
+
+## Goal
+
+Catch regressions that unit tests often miss:
+
+- React render loops
+- route/state oscillation
+- repeated `history.pushState` / `history.replaceState`
+- broken repo switching
+- writable vs read-only state mismatches
+
+## Checklist
+
+1. Open `http://localhost:3000/`.
+2. Let the app settle for 2-3 seconds.
+3. Confirm:
+   - the URL stabilizes instead of flipping repeatedly
+   - there are no React warnings/errors
+   - there is no burst of History API updates
+4. Open one recent writable repo.
+5. In that repo:
+   - click between 2-3 files in the tree
+   - confirm file selection and URL stay in sync
+   - click the sync button once without making edits first
+   - confirm it behaves like a no-op and does not destabilize routing/state
+   - open a markdown note and press the share icon
+   - confirm the dialog opens cleanly, then press cancel without creating/revoking anything
+   - open the repo switcher
+   - navigate home and back into the repo
+   - confirm the workspace still behaves normally
+6. Open one public, non-writable repo.
+7. In that repo:
+   - confirm the read-only state/banner is correct
+   - click a file in the tree
+   - confirm navigation works without edit affordances or loops
+
+## Notes
+
+- Do not use `/new` as the primary smoke for this checklist. It is a lower-value special case than an actual repo workspace.
+- If the change only affects onboarding or the empty/new flow, add a targeted `/new` smoke on top of this checklist rather than replacing it.
+- Record what repo(s) you used and any important observations in the task file or PR notes.

docs/data-layer-notes.md

@@ -0,0 +1,23 @@
+# Data Layer Notes
+
+Short notes on directions we want to preserve while evolving the UI/data boundary.
+
+## Richer Communication
+
+The current model of `dispatch(action)` plus one returned `state` object is useful, but not rich enough for every UI pattern.
+
+Two expansions we want to keep in mind:
+
+- add synchronous `queries` for cached/looked-up data that should not be forced into one durable state object
+- consider an outbound effect/event channel for ephemeral async results that are not naturally durable state
+
+## Example: Repo Probe
+
+`repo.probe` is a good example of data that feels awkward as a single "latest probe" field in app state.
+
+Prefer:
+
+- `dispatch({ type: 'repo.probe', ... })` to request work
+- `queries.getRepoProbe(owner, repo)` to read cached probe results synchronously
+
+This lets the data layer keep a cache of probe results without pretending the latest probe is durable app state.

skills/subagent-manager/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: subagent-manager
+description: Launch, supervise, and review coding subagents in tmux using Codex CLI. Use when breaking work into task files under tasks/, assigning one task per subagent, and reviewing the result before accepting it.
+metadata:
+  skills.sh:
+    emoji: 🤖
+---
+
+# Subagent Manager
+
+Use this skill when work should be delegated to bounded coding subagents instead of being implemented in the main session.
+
+This repo uses a task-board workflow:
+
+- one task file per task under `tasks/`
+- one tmux session per subagent
+- one active workstream per subagent session
+- one bounded task file at a time inside that session
+- manager reviews before accepting the task
+
+## Launch workflow
+
+1. Choose exactly one task file.
+2. Update the task frontmatter before launch:
+   - `status: active`
+   - `assigned: <session-name>`
+3. Launch a tmux-backed Codex session:
+
+```bash
+skills/subagent-manager/scripts/launch-subagent.sh \
+  <session-name> \
+  <model> \
+  <task-file> \
+  "<prompt>"
+```
+
+Example:
+
+```bash
+skills/subagent-manager/scripts/launch-subagent.sh \
+  subagent-define-action-protocol \
+  gpt-5.4 \
+  tasks/define-action-data-protocol.md \
+  "Work only on tasks/define-action-data-protocol.md. Read that task, the relevant parent/audit tasks, AGENTS.md, and only the repo files needed to define the protocol. Update the task file with concise findings, do not implement the protocol, do not change unrelated files, do not commit, and stop when done."
+```
+
+## Prompt rules
+
+Keep the prompt bounded and explicit:
+
+- name the single task file
+- list the minimum context files to read
+- say what kind of work is allowed: audit, design, implementation, validation
+- require the subagent to update the task file before stopping
+- forbid unrelated edits and commits
+- require a short terminal summary before exit
+
+Avoid broad prompts like "work on #99" or "refactor the data layer".
+
+## Reuse policy
+
+Prefer reusing an existing subagent session when:
+
+- the next task is part of the same workstream
+- the session has already gathered relevant codebase context
+- the session output is still sharp and trustworthy
+
+This saves time and context reload cost.
+
+Do not restart a subagent just because one bounded task finished.
+
+Instead:
+
+1. review and accept or reject the finished task
+2. update the next task file
+3. send the next bounded prompt into the same tmux session
+
+Start a fresh subagent session when:
+
+- the workstream changes materially
+- the session starts drifting or freelancing
+- the accumulated context is becoming noisy or stale
+- the prior task revealed that a narrower or differently skilled agent is needed
+
+## Supervision
+
+Inspect the live run with:
+
+```bash
+tmux attach -t <session-name>
+tmux capture-pane -pt <session-name> | tail -n 80
+```
+
+Use subagents for bounded execution, not for silent autonomy. The manager stays responsible for scope control and acceptance.
+
+## Review and acceptance
+
+When the subagent finishes:
+
+1. Review changed files and task output.
+2. Run the relevant checks yourself when code changed.
+3. Accept only if the task file contains useful results and the work matches the brief.
+4. Add `completed:` when a `done` task is accepted.
+5. Kill the tmux session after acceptance or rejection.
+
+Typical review commands:
+
+```bash
+git status --short
+git diff -- <task-file>
+tmux kill-session -t <session-name>
+```
+
+If the result is not acceptable, keep the task open and launch a follow-up subagent with a narrower correction brief.
+
+## Guardrails
+
+- Prefer one subagent per task file.
+- Prefer reusing one good subagent session across adjacent tasks in the same workstream.
+- Prefer one narrow task over one large autonomous run.
+- Do not let subagents commit unless explicitly requested by the user.
+- In this repo, avoid reading or writing `.env`.
+- For code tasks, require `npm run check` and relevant tests unless the task is design-only.
+
+## Safety note
+
+The launcher below uses Codex with dangerous bypass flags because this environment is already externally controlled. If that is not true in another environment, replace those flags with a safer approval/sandbox policy.

skills/subagent-manager/scripts/launch-subagent.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ "$#" -lt 4 ]; then
+  echo "usage: $0 <session-name> <model> <task-file> <prompt>" >&2
+  exit 1
+fi
+
+session_name="$1"
+model="$2"
+task_file="$3"
+prompt="$4"
+repo_root="$(pwd)"
+
+if tmux has-session -t "$session_name" 2>/dev/null; then
+  echo "tmux session already exists: $session_name" >&2
+  exit 1
+fi
+
+tmux new-session -d -s "$session_name" -c "$repo_root"
+tmux send-keys -t "$session_name" \
+  "codex --no-alt-screen -C $repo_root -m $model --dangerously-bypass-approvals-and-sandbox \"$prompt\"" \
+  C-m
+
+echo "launched $session_name"
+echo "task: $task_file"