docs(onboarding): tutorial, templates, and definition-of-done refresh

CHANGELOG.md

@@ -15,12 +15,14 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 - Web recorder stop endpoint (`/api/recorders/web/stop`) and recorder navigation event capture.
 - Recorder draft review panel with reorder/edit/skip controls before inserting recorded steps.
 - Autopilot plan diagnostics: overall confidence score, node-level insights, and fallback template options.
+- Contributor onboarding package: 10-minute tutorial, starter workflow file, and reusable docs templates.
 
 ### Changed
 - CI now includes browser smoke validation (`Web E2E Smoke`).
 - Web editor keyboard shortcuts now include undo/redo and selection-aware delete behavior.
 - Web recorder now follows capture -> review -> insert flow instead of immediate node injection.
 - Autopilot now requires explicit confirm-before-create flow and uses richer starter templates for vague prompts.
+- Onboarding/contributing docs now use change-type contribution paths and an explicit definition-of-done checklist.
 
 ## [1.0.7] - 2026-02-13
 

README.md

@@ -57,9 +57,10 @@ Use these guided demos to evaluate the platform quickly:
 
 ## Contributor Onboarding
 New contributors should start here:
-1. `docs/ONBOARDING.md` (30-minute setup + first contribution path)
-2. `docs/CONTRIBUTING.md` (standards, testing, QA checklist)
-3. `.github/pull_request_template.md` (PR structure used in this repo)
+1. `docs/tutorials/FIRST_AUTOMATION_10_MIN.md` (fast baseline walkthrough)
+2. `docs/ONBOARDING.md` (setup + contribution tracks)
+3. `docs/CONTRIBUTING.md` (standards, definition of done, PR workflow)
+4. `.github/pull_request_template.md` (PR structure used in this repo)
 
 Good first areas:
 - UI polish and node inspector UX (`apps/web/src`)
@@ -127,10 +128,13 @@ Tag pushes (`v*.*.*`) trigger `.github/workflows/release.yml`, which reruns vali
 - `docs/README.md`
 - `docs/DEMOS.md`
 - `docs/ONBOARDING.md`
+- `docs/tutorials/FIRST_AUTOMATION_10_MIN.md`
+- `docs/examples/workflows/first-automation.workflow.json`
 - `docs/ARCHITECTURE.md`
 - `docs/API_REFERENCE.md`
 - `docs/DEPLOYMENT.md`
 - `docs/CONTRIBUTING.md`
+- `docs/templates/*`
 - `AGENTS.md` (repository contributor guide)
 - `CHANGELOG.md`
 - `CODE_OF_CONDUCT.md`

docs/CONTRIBUTING.md

@@ -1,31 +1,27 @@
 # Contributing to ForgeFlow
 
-This guide standardizes local setup, coding practices, and contribution workflow.
+This guide standardizes setup, engineering quality, and PR delivery.
 
-Start here if you are new:
-- `docs/ONBOARDING.md` for the fastest first-PR path.
-- `docs/DEMOS.md` for repeatable product walkthrough flows.
-- `CODE_OF_CONDUCT.md` for expected behavior in community interactions.
+Start here if new:
+- `docs/ONBOARDING.md`
+- `docs/tutorials/FIRST_AUTOMATION_10_MIN.md`
+- `CODE_OF_CONDUCT.md`
 
 ## 1. Prerequisites
-
 - Docker + Docker Compose
-- Node.js 20+ (for local non-container development)
-- Python 3.11+ (for local agent work)
-- Linux desktop/X11 setup if working on desktop automation flows
+- Node.js 20+
+- Python 3.11+ (for `apps/agent` work)
 
 ## 2. Development Setup
 
-## Option A: Recommended (Docker)
-
+Recommended:
 ```bash
 ./start.sh
 ```
 
-## Option B: App-by-app local development
+App-by-app local setup:
 
 Server:
-
 ```bash
 cd apps/server
 npm install
@@ -34,15 +30,13 @@ npm run dev
 ```
 
 Web:
-
 ```bash
 cd apps/web
 npm install
 npm run dev
 ```
 
 Agent:
-
 ```bash
 cd apps/agent
 python -m venv .venv
@@ -52,108 +46,84 @@ uvicorn main:app --host 0.0.0.0 --port 7001
 ```
 
 ## 3. Project Layout
-
-- `apps/web`: React/Vite frontend, node graph UI, diagnostics panels.
-- `apps/server`: Express API, runner, scheduler, auth, stores, metrics.
-- `apps/server/prisma`: schema + migrations.
-- `apps/agent`: FastAPI desktop automation service.
-- `docs`: architecture/API/deployment/contribution docs.
-- `deploy/k8s`: Kubernetes starter manifests.
-
-## 4. Code Standards
-
-- TypeScript and Python code should be explicit and readable.
-- Keep functions focused; avoid large multi-responsibility handlers.
-- Prefer schema validation (`zod`) for new API inputs.
-- For protected endpoints, always apply `requirePermission`.
-- Write audit events for security-sensitive or admin actions.
-- Keep log entries structured and actionable.
-- Avoid introducing magic constants; use named config/env values.
-
-## 5. Testing Expectations
-
-## Backend tests
-
+- `apps/web`: React/Vite UI and workflow builder
+- `apps/server`: Express API, runner, scheduler, auth, stores
+- `apps/server/prisma`: schema and migrations
+- `apps/agent`: FastAPI desktop bridge
+- `docs`: architecture/API/deployment/onboarding
+
+## 4. Contribution Paths by Change Type
+
+### A. Web/UI Changes
+- Touchpoints: `apps/web/src/*`
+- Also update: screenshots/GIFs in PR for behavior changes
+- Required validation:
 ```bash
-docker compose run --rm server npm test
+cd apps/web && npm test && npm run build
 ```
 
-Critical path subset:
-
+### B. Server/API/Runner Changes
+- Touchpoints: `apps/server/src/*`
+- Expectations:
+  - add input validation (`zod`) for new API contracts
+  - apply permission checks for protected endpoints
+  - write audit events for sensitive/admin operations
+- Required validation:
 ```bash
-docker compose run --rm server npm run test:critical
+cd apps/server && npm test && npm run build
 ```
 
-Web UI tests:
-
+### C. Docs/Community Changes
+- Touchpoints: `README.md`, `docs/*`, `.github/*template*`
+- Expectations:
+  - commands and paths are runnable/accurate
+  - docs reflect current merged behavior
+
+## 5. Templates for Consistency
+Use these templates when applicable:
+- `docs/templates/activity-proposal.md`
+- `docs/templates/node-implementation-checklist.md`
+- `docs/templates/demo-script-template.md`
+
+## 6. Testing and CI
+CI in `.github/workflows/ci.yml` runs on PRs and `main` pushes:
+- `Server Test and Build`
+- `Web Test and Build`
+- `Web E2E Smoke`
+
+Recommended full local validation before review:
 ```bash
-cd apps/web
-npm test
-```
-
-Web E2E smoke tests (Playwright):
-
-```bash
-cd apps/web
-npx playwright install --with-deps chromium
-npm run test:e2e
+cd apps/server && npm test && npm run build
+cd apps/web && npm test && npm run build
 ```
 
-Test locations:
-- `apps/server/src/**/*.test.ts`
-
-When adding features:
-- Add/extend unit tests for new logic.
-- Add API behavior tests for validation/permission edges where feasible.
-- For run-engine features, include success and failure-path coverage.
-
-CI gate:
-- GitHub Actions workflow `.github/workflows/ci.yml` runs server/web test+build on every PR.
-- CI also runs Playwright smoke tests (`Web E2E Smoke`).
-- Keep CI green before asking for review or merge.
-
-Release flow:
-- Use root scripts to tag next version from `main`:
-  - `npm run release:patch`
-  - `npm run release:minor`
-  - `npm run release:major`
-- Tag push triggers `.github/workflows/release.yml`, which reruns verification and creates the GitHub release.
-- Record user-facing changes in `CHANGELOG.md`.
-
-## 6. Manual QA Checklist
-
-Before submitting:
-- [ ] Login/logout flow works.
-- [ ] Workflow create/edit/save/publish works.
-- [ ] Quick-add node search works (`Ctrl/Cmd+K`, type, `Enter`).
-- [ ] Duplicate selected node works (`Ctrl+D` and toolbar button).
-- [ ] Autopilot workflow generation works from sidebar prompt.
-- [ ] Orchestrator robot/job queue flow works (create robot, queue job, dispatch/sync).
-- [ ] Process mining panel loads and shows opportunities/bottlenecks.
-- [ ] Test run and production run both work.
-- [ ] Approval/resume behavior works for `manual_approval`.
-- [ ] Run diagnostics logs/artifacts render correctly.
-- [ ] Document understanding and clipboard AI transfer nodes validate and run as expected.
-- [ ] New UI interactions show success/error feedback.
-- [ ] No regressions in schedule and template flows.
-
-## 7. Pull Request Guidelines
-
-- Use focused commits and clear messages.
-- Include what changed, why, and how to validate.
-- Include screenshots/GIFs for UI behavior changes.
-- Mention any migration or env var changes explicitly.
-- Update `README.md`, `QUICKSTART.md`, and/or `docs/*` when behavior changes.
-
-## 8. Security and Secrets
-
-- Never commit real secrets or personal credentials.
-- Use `.env.example` for new config keys.
-- If adding auth, RBAC, webhook, or secret features, include abuse-case considerations and tests.
-
-## 9. Documentation Rule
-
-Feature work is not complete until:
-- API changes are reflected in `docs/API_REFERENCE.md`.
-- architecture-impacting changes are reflected in `docs/ARCHITECTURE.md`.
-- deployment-impacting changes are reflected in `docs/DEPLOYMENT.md`.
+## 7. Definition of Done
+A PR is done only when all are true:
+- [ ] Scope is focused and the title/description are clear.
+- [ ] Required tests/build commands pass.
+- [ ] API/UI behavior changes are documented.
+- [ ] `CHANGELOG.md` updated for user-visible changes.
+- [ ] Risk and rollback notes are included in PR.
+
+## 8. Pull Request Guidelines
+- Branch naming: `feat/<topic>`, `fix/<topic>`, `docs/<topic>`.
+- Commit messages: concise, imperative (`feat(recorder): add draft review panel`).
+- Use `.github/pull_request_template.md`.
+- Include:
+  - what changed and why
+  - exact validation commands run
+  - screenshots/GIFs for UI changes
+  - docs updated
+
+## 9. Release Flow
+From `main`, create the next tag:
+- `npm run release:patch`
+- `npm run release:minor`
+- `npm run release:major`
+
+Tag push triggers `.github/workflows/release.yml` and publishes GitHub release notes.
+
+## 10. Security and Secrets
+- Never commit real secrets.
+- Add new env vars to `.env.example`.
+- For auth/RBAC/webhooks/secrets changes, include abuse-case considerations and tests.

docs/ONBOARDING.md

@@ -1,6 +1,6 @@
 # Contributor Onboarding
 
-This guide helps new contributors deliver a first high-quality PR quickly.
+This guide helps new contributors ship a first high-quality PR quickly.
 
 ## 1. Prerequisites
 - Docker + Docker Compose
@@ -20,51 +20,62 @@ Default local login:
 - username: `local`
 - password: `localpass`
 
-## 3. Understand the Repo Fast
-- `apps/web`: workflow studio UI
-- `apps/server`: API, runner, scheduling, auth, orchestration
-- `apps/agent`: desktop automation bridge
-- `docs`: architecture, API, deployment, contribution docs
-
-## 4. Choose a First Task
-Recommended starter contributions:
-- UI improvements in `apps/web/src/components`
-- Add/extend node behavior in `apps/server/src/lib/runner.ts`
-- Add endpoint + tests in `apps/server/src/index.ts` + `src/lib/*.test.ts`
-- Improve docs/tutorials in `docs/*`
-
-## 5. Development Workflow
-1. Create branch
+## 3. Do the 10-Minute Tutorial First
+Use the guided tutorial and starter workflow:
+- `docs/tutorials/FIRST_AUTOMATION_10_MIN.md`
+- `docs/examples/workflows/first-automation.workflow.json`
+
+This gives you a known-good baseline before deeper changes.
+
+## 4. Choose a Contribution Track
+
+### Web/UI track
+- Primary files: `apps/web/src/*`
+- Typical work: canvas UX, inspector fields, sidebar features
+- Required validation:
 ```bash
-git checkout -b feat/<short-topic>
+cd apps/web && npm test && npm run build
 ```
-2. Implement change
-3. Run validation:
+
+### Server/Runtime track
+- Primary files: `apps/server/src/*`
+- Typical work: runner nodes, APIs, authz, orchestrator logic
+- Required validation:
 ```bash
 cd apps/server && npm test && npm run build
-cd apps/web && npm test && npm run build
 ```
-4. Update docs for behavior/API changes
-5. Commit with clear message (example: `feat(orchestrator): add queue status sync`)
-
-## 6. Pull Request Checklist
-Use `.github/pull_request_template.md` and include:
-- What changed and why
-- How to test (exact commands)
-- Screenshots/GIF for UI changes
-- Docs updates performed
-- Risk/rollback notes for non-trivial changes
-
-## 7. Community Standards in This Repo
-- Keep commits focused and reviewable.
-- Add tests for new logic and edge cases.
-- Validate permissions for protected API changes.
-- Write audit events for sensitive/admin actions.
-- Keep docs current with features.
+
+### Docs/Enablement track
+- Primary files: `README.md`, `docs/*`, `.github/*template*`
+- Typical work: tutorials, examples, contribution process, demo scripts
+- Required validation: link/command accuracy and consistency with current behavior
+
+## 5. Use Repository Templates
+Start from templates in `docs/templates` when relevant:
+- `activity-proposal.md`
+- `node-implementation-checklist.md`
+- `demo-script-template.md`
+
+## 6. Pull Request Path
+1. Create branch:
+```bash
+git checkout -b feat/<short-topic>
+```
+2. Implement focused changes.
+3. Run required validation for your track.
+4. Update docs affected by behavior/API/UI changes.
+5. Fill `.github/pull_request_template.md` completely.
+
+## 7. Definition of Done (Required)
+- [ ] Changes are scoped and reviewable.
+- [ ] Required tests/builds pass.
+- [ ] User-facing/API behavior is documented.
+- [ ] Demo/tutorial updates are included when UX flows change.
+- [ ] PR includes rollback/risk notes.
 
 ## 8. Where to Ask Questions
 - Open a draft PR early with assumptions.
-- Link relevant files and failing tests directly.
-- Keep scope explicit to speed up review.
+- Link exact files and failing commands.
+- Keep scope explicit to reduce review churn.
 
-Tip: prefer small PRs (<300 changed lines) to keep review cycles fast.
+Tip: prefer small PRs (<300 changed lines) unless the feature requires a larger vertical slice.