Skip to content

Day-one readiness

The team dashboard is not proof that the product runs on a member's computer. Use this checklist during each person's onboarding. Record actual results and remaining blockers; do not mark a person ready from a folder check alone.

Start small

During the first week, focus on four requests: today, start my task, report a bug, done for today. Learn one AI foundations topic at a time. The Academy, backlog and trek remain available; nobody needs to master all tabs or commands on day one. Introduce optional backlog work after one complete task.

Use a terminal, VS Code or Antigravity. Ask the AI to name the relevant team skill, read the assigned task and give one next step. An editor opening successfully does not prove the AI read the instructions.

Engineer setup: a personal local database

Prefer one local development database per engineer initially. Do not copy a live customer database or use production credentials for onboarding. Keep .env local and ignored. Share required development service credentials through an approved private secret-sharing channel, never through docs, chat screenshots or Git. A shared password vault is a possible team choice; no vault has been provisioned by this change.

Read the sibling repository's instructions and environment example first. The following is an inspection-based setup sequence, not a verified installation on either engineer's machine:

  1. Confirm Node and the required dependencies from the product repositories.
  2. In nepwalk-be, copy .env.example only if .env does not already exist. Configure a local database URL, matching database username/password/name, and fresh development JWT secrets. Never overwrite an existing environment file.
  3. Start only the PostgreSQL service with docker compose up -d db, or use an existing personal local PostgreSQL instance. Check port conflicts first.
  4. When running the API on the host, use localhost and the published database port in DATABASE_URL; the example's db hostname is for a container network.
  5. Confirm the target is the personal development database before running:
npm ci
npx prisma generate
npx prisma migrate deploy
npm run db:seed
npm run start:dev
  1. Check the API health endpoint at http://localhost:3001/api/v1/health. A healthy API does not prove Google sign-in, email or all user journeys work.
  2. In nepwalk-fe, use the repository's environment example and scripts. Set the API URL to the development API and use the same Google client ID as the backend. The ID itself is public, but its allowed origins must include the local frontend.
  3. Verify a real sign-in and one assigned journey. Save the tested revision, environment, result and any missing service configuration.

Do not run reset/clean commands as a default recovery step; they can remove local work or database volumes. Test databases must be separate from development data.

Backend gaps found during repository inspection

These were observed in the current files; they have not been repaired or proved on a clean machine in this docs change:

  • docker-compose.yml hardcodes the API database URL, so changing the database environment variables alone can leave the API pointing at different credentials.
  • The Docker startup command uses ts-node-dev, which is absent from package.json. A clean start may attempt a network install instead of using a declared dependency.
  • The README says startup seeds data, but the inspected startup command and entrypoint do not run the seed. Seed explicitly against the local database.
  • No backend GitHub Actions workflow was present. A backend CI task still needs its own validated setup: temporary test PostgreSQL, migrations, generation, type checks, lint and tests. Do not run CI against a developer or live database.

Niwesh: tests on his own machine (A24)

Niwesh runs the frontend and backend locally, exactly like an engineer: his own local database, his own .env, the seed data, then nepwalk-be on port 3001 and nepwalk-fe on port 3000. Follow the engineer setup above; his AI tool helps.

Each test assignment names the commit or branch to test, the fictional test accounts, the acceptance checks and who to contact when blocked. If the apps do not start, record an environment blocker rather than a failed product test.

Previews are not the test environment.

Do not assume every contributor's Vercel preview builds. Vercel documents commit author restrictions for private-repository Hobby deployments, plus separate restrictions for organization-owned private repositories. The actual repository visibility, plan and project access need checking before choosing a deployment route. See Vercel collaboration rules and Git deployment rules.

A paid plan or a separately deployed staging site is a founder decision. Do not rewrite author identity, expose a private repository or share a personal token to work around deployment restrictions.

Thirty-minute rehearsal

Use an isolated temporary copy with fictional records, not the shared progress history. Have a person try the actual AI tools the team will use:

  1. Identify as a test engineer and ask for today. The AI must read current records.
  2. Open a fictional task. Check that it stops for real manual testing.
  3. Report a fictional bug with a redacted screenshot. Inspect the saved attachment.
  4. Learn one concept, give a deliberately incomplete explanation, and check that the AI asks a question instead of marking it understood.
  5. Close the day. Check that unfinished work stays open and hours are confirmed.

Record the tool, revision, which steps passed and what blocked the rest. This rehearsal has not been performed by this documentation change.

Sharing and review

The dashboard reads a local snapshot or connected folder. Merged records are not live telemetry. Show the source clearly and refresh before planning from it. Members can hand off at a useful checkpoint; Prakash decides when to review and merge. Set a review window together before launch rather than inventing a time.

One task at a time and independent review remain the policy. Under A24, Niwesh may accept P2/P3 work of others; P0/P1 acceptance stays with the founder. Nobody accepts their own work. Founder-owned P0/P1 work has no eligible acceptor under this rule: resolve task ownership or explicitly revise the policy before proceeding. Auto-merging records is not enabled: a records-only change can still alter an assignment, award or acceptance state. Passing validation does not establish who was authorized to make that decision.

Checks before launch

  • [ ] Shankalpa: local API, frontend, sign-in and one journey verified.
  • [ ] Anish: local API, frontend, sign-in and one journey verified.
  • [ ] Umang: local API, frontend, sign-in and one journey verified.
  • [ ] Niwesh: reachable test environment and known revision verified.
  • [ ] Each member: own Git access and AI skill loading demonstrated.
  • [ ] A real docs pull request passes Docs and team checks / verify.
  • [ ] Founder configures the successful check as required in repository settings.
  • [ ] Backend CI is implemented and verified on a clean test database.
  • [ ] Team agrees on a review window and escalation contact.

The docs workflow is now defined in .github/workflows/ci.yml. It runs tests, record validation, script syntax checks, a strict docs build and repository hooks. It becomes active after the workflow is pushed; branch protection and the first GitHub-hosted run still need verification.