This file provides the small set of project-wide instructions agents should read before working in Better-Fullstack. Keep detailed, area-specific guidance in `docs/guidelines/` instead of growing this file with task notes. For documentation work or when the right source of project knowledge is unclear, read `docs/README.md`. It defines document authority and routing. ## Guidelines Do not bulk-read `docs/guidelines/`. Open a guideline when the request matches its topic. One exception is mandatory, not optional: adding any new library, tool, or category to any ecosystem requires reading `docs/guidelines/adding-new-tool-options/` first. See `docs/guidelines/` for deeper reference on these topics: - `README.md` - folder purpose, usage rules, and quick index for all guideline files - `architecture-and-ownership.md` - monorepo package ownership and where changes belong - `stack-graph-and-config-authority.md` - graph authority, Role Binding ownership, flat projections, and graph-safe mutations - `lifecycle-commands-and-mcp.md` - create/add/update/check semantics, plan/apply safety, baselines, and CLI/MCP parity - `generated-artifacts-and-sync.md` - generated-file producers, authoritative inputs, and safe regeneration in dirty worktrees - `telemetry-privacy-and-internal-tools.md` - telemetry allowlists, ingest privacy, aggregate access, and fail-closed internal tools - `public-docs-i18n-and-seo.md` - public content authority, translation fallback, schema-derived references, and agent/SEO surfaces - `capability-evidence-levels.md` - shared public proof levels and fail-closed claim rules - `stack-options-and-compatibility.md` - schema source of truth, canonical option metadata, aliases, and compatibility rules - `generator-change-playbook.md` - generated-output constraints, template changes, and verification - `web-builder-and-url-state.md` - stack builder state, URL parsing, lazy-route constraints, and preview wiring - `testing-release-and-upstream.md` - targeted verification commands, release guard expectations, and upstream backport workflow - `preview-publishing-security.md` - PR preview threat model, trusted artifact boundary, environment setup, and workflow guard - `adding-new-tool-options/` - **read this subfolder when adding any new library, tool, or category** to any ecosystem. Use its README for the source checklist, graph/CLI/MCP wiring, routing constraints, and verification ## Web UI `apps/web` has established primitives - tabs, copy buttons, command/code bars, cards. Before adding any UI control, grep `apps/web/src/components` for an existing one and reuse it. Do not introduce a second visual language for a control that already exists (no pills where the app uses tabs). New visual patterns need Ibrahim's sign-off. ## Workflow - Prefer concise, simple solutions. If a problem can be solved in a simpler way, propose it. - If asked to do too much work at once, stop and say so clearly. - Use `testing/README.md` for prompt-free scaffolds, published-package validation, and runtime-proof lanes. - Never start the dev server (`turbo dev`, `bun run dev`, `vite dev`, etc.) unless explicitly asked to. - After code changes, run the smallest verification set that proves the modified area still works. Prefer package-local `bun run lint`, `bun run test`, `bun run build`, or specific `bun test ` commands over broad workspace sweeps. - For release-sensitive stack or generator changes, run `bun run test` and `bun run test:release` from the repo root. `bun run test` covers template snapshots and CLI/builder parity; `test:release` covers the release validators. ## Bun Bun is the default package manager and script runner. Use `bun install`, `bun run