Developer Onboarding

This walks a new contributor through the editor-neutral setup in the repository root's DEVELOPMENT.md, expanded with the reasoning behind each step. Follow it in order the first time; after that, npm run dev:sable is the only command you need daily.

What you need before you start

• Git access to Indigo-Trigger/indigo-trigger-engagement on GitHub.
• Node.js 22 and npm.
• The GitHub CLI (gh), for opening pull requests.
• The Supabase CLI, for backend inspection.
• Vercel CLI access to cprinos-7741s-projects/sable, for the full local API runtime (vercel dev).

You can work on code and tests before Vercel access is provisioned — see "Working without Vercel access" below. You cannot reach live data or deploy anything without it.

Five-minute start

nvm use
npm run bootstrap
npm run doctor
npm run setup:gitnexus
npm run doctor:claude
git fetch origin
git switch -c your-name/short-description origin/main
npm run dev:sable

Run all of this from the repository root, not from inside sable-agents-demo/. Here is what each command does and why it exists:

Command	What it does	Why it matters
npm run bootstrap	Installs all four JavaScript workspaces (sable-agents-demo, sable-agents-demo/web, sable-agents-demo/supabase, sable-agents-demo/docs-site) from their committed lockfiles.	It does not download secrets, link a cloud project, or touch production — safe to run on a machine with no access yet.
npm run doctor	Checks runtime versions, repository state, dependencies, required CLIs, and GitHub/Supabase/Vercel access.	Surfaces missing access before you waste time on a task you cannot finish. Add -- --offline to skip the cloud checks, or -- --strict to fail on missing optional access.
npm run setup:gitnexus	Builds or refreshes the local GitNexus code-intelligence index used by Claude Code sessions in this repo.	Root-only script — it does not run from inside sable-agents-demo/.
npm run doctor:claude	Validates Claude Code itself, the repo-local skills, MCP configuration, and the destructive-command safety hook.	Confirms the guard that blocks git push --force, git reset --hard, and rm -r is actually wired up before you start an AI-assisted session.
npm run dev:sable	Starts static pages and web/api/*.js together with vercel dev.	This is the only way to exercise the API routes locally; opening the HTML files directly serves no /api/* responses.

Open the right folder for an AI-assisted session

If you use Claude Code, open sable-agents-demo/ as the project root, not the repository root and not sable-agents-demo/web/ alone:

• The repository root has no .mcp.json — GitNexus and Supabase MCP servers never load there.
• sable-agents-demo/web/ alone loses the parent directory's safety hook and MCP configuration.
• sable-agents-demo/ is where .mcp.json, .claude/settings.json, CLAUDE.md, the web app, Supabase backend, and Trigger tasks all live together.

New to Claude Code entirely? Read docs/onboarding/06-claude-code-quickstart.md first, then start with cd sable-agents-demo && claude.

Working without Vercel access

Vercel access is often the slowest access grant to land. While you wait, code and tests are fully reachable:

npm --prefix sable-agents-demo/web test
npm test

You cannot run vercel dev or see live-data pages without it, but you can write and test route handlers, fix bugs with a reproducing test, and review code.

The safe issue workflow

1. Start from current origin/main on a feature branch — never work from a stale local main.
2. Reproduce the reported behavior yourself. An AI-suggested fix is a hypothesis, not evidence that the cause is understood.
3. Add a failing regression test wherever the behavior is testable.
4. Make the smallest change that fixes the reproduced problem.
5. Run the targeted test, then npm run check (the local equivalent of SABLE CI: manifests, tests, typecheck, and docs build) before opening a PR.
6. Push the branch and open a PR against main; use the Vercel preview deployment for browser verification, not a local guess.
7. Merge only after required checks and review pass.

Access map

Access	Needed for	Owner / next step
GitHub repository	Branches, PRs, checks	Chris Prinos or a repository administrator
Vercel team cprinos-7741s-projects, project sable	Full vercel dev, logs, previews	Chris Prinos
Supabase project fvngkfrmienkltuwtoxa	Backend inspection and approved backend work	Chris Prinos or the SABLE operator
Trigger.dev project	Durable report and automation work	SABLE operator
SABLE feedback records (e.g. SABLE-000014)	Reproduction and triage	SABLE Development surface

Ask an owner for the approved local or preview configuration. Never paste secret values into source, issues, Slack, email, or an AI chat, and never copy production service-role credentials into a personal .env without explicit approval.

The production boundary, from day one

feature branch -> pull request -> required checks -> merge to main -> automated deployment

Never run a direct production Vercel deploy, promotion, redeploy, or alias change from a workstation. Never run supabase db push, deploy an Edge Function, or deploy a Trigger task from a workstation — the main-branch CI workflows own those production changes. Read-only Supabase inspection is fine; schema changes are new migrations reviewed in a PR. Before telling anyone a change is live, verify the merged commit is contained in origin/main and that the production deployment was created from that history.

Where things live

Area	Location
Web pages and serverless API	sable-agents-demo/web/
Supabase migrations, functions, and helper tests	sable-agents-demo/supabase/
Trigger.dev tasks	sable-agents-demo/trigger/
Environment-name manifests	sable-agents-demo/env-manifests/
Operator and product docs (this site)	sable-agents-demo/docs-site/
Managed-agent source, prompts, skills	sable-agents-demo/agents/, prompts/, skills/

Where the code lives

• DEVELOPMENT.md (repository root) — the canonical, editor-neutral onboarding source this page expands.
• SABLE.md (repository root) — production identity, deployment truth, and the naming note about the legacy sable-agents-demo/ directory name.
• sable-agents-demo/CLAUDE.md — area-specific safety rules for AI-assisted sessions.
• scripts/developer/bootstrap.mjs, scripts/developer/doctor.mjs, scripts/developer/doctor-claude.mjs.
• .github/workflows/sable-ci.yml — the CI jobs npm run check approximates locally.