Your first developer change

This guide is for a developer new to this repository. You will run the fictional demo, understand where code belongs, and change the existing example module. The first exercise does not add a database table or send anything externally.

Start the app

You need Git, Node.js 22 or later, npm and an editor. Start from the published main branch for a local experiment.

node --version
npm --version
git clone https://github.com/JohnConnorCode/accelerate-site.git
cd accelerate-site
git rev-parse HEAD

For an assigned Feature Board task, use the approved repository base and exact commit in its live execution packet. Resolve a mismatch before changing code.

Then install and start the app:

npm ci
npm run dev

Run the remaining commands from the cloned repository, where package.json lives. npm ci installs the versions recorded in the lockfile. npm run dev starts the local development server; it does not publish the application.

Open the URL printed by the terminal, then visit /demo/command-center. You should see a fictional business workspace. Follow your first workflow to learn the behavior before changing code. Stop your own server with Control-C when finished.

Find the right files

You want to change…	Start here
A page or request entrypoint	src/app/
Reusable interface pieces	src/components/
Business rules and reusable operations	src/lib/revenue-os/
Module registration	extensions/
Public product guides	src/content/docs/ and its manifest.ts
Database structure	Ordered migrations and the migration manifest

Read docs/NORTHSTAR.md and then AGENTS.md before implementation. For coordinated repository work, follow the live Feature Board contract; a local experiment is not a claimed or completed board ticket.

Make one small change

The repository includes an Inventory example. Its manifest registers a page and workspace toggle; it does not implement stock storage or automatic reordering.

1. Open src/app/admin/example-inventory/page.tsx in your editor.
2. Find the heading “This page is registered by a manifest” and change it to “My first workspace extension”. Save the file.
3. Read extensions/example-inventory.module.json. Its routes field names the page you edited. It ships with defaultEnabled: false; leave that setting unchanged for this exercise.
4. In another terminal in the repository, run the checks below. These confirm registration consistency; they do not prove database permissions or a rendered page.

npm run verify:extensions
git diff --check
git diff -- src/app/admin/example-inventory/page.tsx

The diff should contain only your intended text change. You do not need to regenerate module registration when only page text changes.

See the extension in a workspace

The public demo demonstrates selected fictional workflows. To inspect this admin extension, use a connected local installation with an administrator account.

Open /admin/integrations, enable the Inventory example for your test workspace, and visit /admin/example-inventory. Confirm your heading appears. Disable the module and confirm the route refuses access. This is a workspace feature check; it does not require enabling the example for other workspaces.

Turn the example into a real feature

Add a module covers a new manifest and route. A real feature also needs explicit business behavior, validation, authorization, storage if required, and meaningful tests. A manifest does not create those for you.

Keep business writes in the shared domain services so the UI, AI tools, and integrations use the same rules. External effects need approval where required, idempotency, and a truthful result. Read the engineering and tenancy contracts linked from AGENTS.md before adding a write path.

Run the affected checks and the repository's required verification before submitting application code. Use one heavy job at a time or CI; do not start parallel builds or copy dependency trees to work around resource limits.

Keep developing through the backlog

Run npm run dev:doctor to check local readiness. To join coordinated work, obtain a project-scoped work token from the project owner, configure WORK_BOARD_URL and WORK_BOARD_TOKEN, and run npm run dev:doctor -- --board. Contributors do not need the owner’s database credentials.

Use npm run agent:status to inspect ready work and npm run agent:show -- --card <key> to read a task before claiming it. npm run agent:next claims a dependency-ready task and creates its isolated worktree. Follow its live acceptance criteria, renew the lease with agent:heartbeat, and submit named checks and the exact commit with agent:complete -- --card <key> --evidence-file <path.json>. Submission, review, merge and deployment are separate recorded steps. The full command contract is in AGENTS.md and its linked developer handoff.

Every feature change also updates the organized public guides, product changelog and Command Center descriptions in the same pull request. Keep planned capabilities clearly separate from available behavior. Report new gaps through the live board so the next contributor has a concrete task and verification criteria.

Next: Add a module. If something failed, use Troubleshooting.