docs: refresh public documentation for current runtime

Author: bitifirefly

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,33 +1,43 @@
 > [!IMPORTANT]
 >
-> 1. Read [CONTRIBUTING.md](../CONTRIBUTING.md)
-> 2. Ensure issue exists and you're assigned
-> 3. Link correctly: `Fixes #<issue number>`
+> - Target `develop` unless a maintainer explicitly asked for a `main` hotfix/release PR.
+> - Read [CONTRIBUTING.md](../CONTRIBUTING.md).
+> - Link the issue correctly, for example: `Fixes #123`.
 
-## What & Why
+## Summary
 
-**What**: Brief description
-**Why**: Problem solved
+Briefly describe what changed.
 
-Fixes #(issue number)
+## Why
 
-## Pre-PR Checklist
+Explain the problem, risk, or user need this PR addresses.
 
-Run these:
+Fixes #
+
+## Validation
 
-- [ ] `pnpm type-check`
 - [ ] `pnpm format:check`
-- [ ] `pnpm lint`
-- [ ] `pnpm build`
-- [ ] `pnpm i18n:check` (if applicable)
+- [ ] `pnpm gate:quality:verify`
+- [ ] `pnpm test`
+- [ ] `pnpm build:all`
+- [ ] `pnpm i18n:check` (if translations changed)
+- [ ] Manual or targeted tests are described below when full test coverage was not run
+
+### Test Notes
+
+Describe manual checks, targeted tests, screenshots, or why some checks were skipped.
+
+## Docs and Ops Impact
 
-## Type
+- [ ] No public doc changes required
+- [ ] Updated `README.md` and/or `docs/*` for public behavior changes
+- [ ] Added or updated `.env*.example` entries for new runtime configuration
+- [ ] Database / migration impact explained below
+- [ ] Deployment / CI impact explained below
 
-- [ ] 🐛 Bug fix
-- [ ] ✨ Feature
-- [ ] 💥 Breaking change
-- [ ] 📚 Docs
-- [ ] ♻️ Refactor
-- [ ] ⚡ Performance
+## Checklist
 
-## Screenshots (if UI changes)
+- [ ] Commit messages follow the repository's Conventional Commit style
+- [ ] The PR is scoped to one logical change set
+- [ ] New routes, rewrites, or cutovers do not leave stale public docs behind
+- [ ] UI changes include screenshots when relevant

CONTRIBUTING.md

@@ -1,63 +1,109 @@
 # Contributing Guide
 
+## Base Branch
+
+- Use `develop` for normal feature, fix, and documentation work.
+- Only target `main` when a maintainer explicitly asks for a release or hotfix PR.
+
 ## Quick Setup
 
-**Prerequisites**: Node.js 18.17+, pnpm 8.0+, Git
+### Prerequisites
+
+- Node.js 22+
+- Corepack or pnpm `10.14.0`
+- Git
+- PostgreSQL, Redis, and MinIO if you want to run the full stack locally
+
+### Clone and Install
 
 ```bash
-# 1. Fork & Clone
-git clone https://github.com/ifLabX/AgentifUI.git
-cd AgentifUI
-pnpm install
+git clone https://github.com/iflabx/agentifui.git
+cd agentifui
+
+corepack enable
+corepack prepare pnpm@10.14.0 --activate
+pnpm install --frozen-lockfile
+```
+
+### Configure Local Runtime
 
-# 2. Setup
+```bash
 cp .env.example .env.dev
-# Edit .env.dev
+# edit .env.dev for your local PostgreSQL / Redis / MinIO / auth settings
+```
+
+### Create a Working Branch
 
-# 3. Create Branch
-git checkout -b feat/your-feature  # or fix/issue-name
+```bash
+git switch develop
+git pull
+git switch -c feat/your-change
+```
+
+## Daily Commands
+
+```bash
+pnpm dev:all          # Next.js + Fastify together
+pnpm dev:web          # Next.js only
+pnpm dev:api          # Fastify only
+pnpm type-check
+pnpm lint
+pnpm test
+pnpm build:all
+pnpm gate:quality:verify
 ```
 
-## Development Commands
+If you change translations, also run:
 
 ```bash
-pnpm dev          # Start dev server
-pnpm type-check   # TypeScript check
-pnpm format:check # Format check
-pnpm lint         # Lint check
-pnpm build        # Build test
-pnpm i18n:check   # Translation check
+pnpm i18n:check
 ```
 
-## Before PR
+## Before Opening a PR
 
-Required checks:
+Run the relevant checks locally:
 
 ```bash
-pnpm type-check && pnpm format:check && pnpm lint && pnpm build
+pnpm format:check
+pnpm gate:quality:verify
+pnpm test
+pnpm build:all
 ```
 
-## Process
+Notes:
 
-1. **Fork** → **Branch** → **Code** → **Test** → **PR**
-2. **Commit format**: `type(scope): description`
-3. **CLA**: Sign at https://cla.iflabx.com (required for external contributors)
+- `pnpm build` only covers the Next.js app. Use `pnpm build:all` before a PR so shared and Fastify packages are checked too.
+- If you only run targeted tests, explain that in the PR description.
+- If you change runtime behavior, public routes, configuration, or deployment flow, update `README.md` and the relevant files under `docs/` in the same PR.
 
-## Issue Guidelines
+## Pull Request Expectations
 
-**Bug reports**: Include environment, steps, expected vs actual
-**Feature requests**: Include problem, solution, use cases
+1. Keep each PR focused on one change set.
+2. Link the issue or explain why the PR is needed.
+3. Call out database, environment-variable, deployment, or CI impact.
+4. Include screenshots for visible UI changes.
+5. Prefer follow-up PRs over mixing refactors and behavior changes into one large submission.
+
+## Commit Style
+
+Use Conventional Commits where practical:
+
+- `feat:`
+- `fix:`
+- `docs:`
+- `refactor:`
+- `test:`
+- `chore:`
 
 ## Standards
 
-- **Code**: TypeScript/React with Prettier
-- **Commit types**: feat, fix, docs, style, refactor, perf, test
-- **Dependencies**: Apache 2.0/MIT/BSD only, discuss in issues first
+- Use `pnpm`, not `npm` or `yarn`.
+- Keep TypeScript and ESLint warnings under control; do not bypass quality gates without a clear reason.
+- Update `.env*.example` when adding or renaming public runtime configuration.
+- Do not leave dead route paths or outdated docs behind after a cutover.
 
 ## Support
 
-- **Issues**: Bug reports & features
-- **Discussions**: Questions & community
-- **Docs**: Check [./docs/](./docs/) first
-
-**CLA**: By submitting code, you agree it may become part of future releases under the CLA terms.
+- Start with `README.md` and `docs/`.
+- Use GitHub Issues for bugs and feature requests.
+- External contributors must complete the CLA flow if the repository requests it.