nurosys-agents 2.0.0

package/.agent/frontend/skills/architect/SKILL.md

@@ -0,0 +1,644 @@
+---
+name: architect
+description: Research the current React/Next.js codebase, decompose a feature or enhancement into logical modules with dependency ordering, and produce a gated architecture plan plus per-module implementation prompts. Use when the user asks to architect, break down, design, or phase a multi-file feature, module, refactor, or enhancement.
+---
+
+# Skill: architect
+
+Use this skill when the work is larger than a small single-file change and you need a reusable implementation blueprint before coding.
+
+The goal is to:
+
+1. Study the existing this architecture first.
+2. Break the requested work into small, independently implementable modules.
+3. Produce one master architecture plan.
+4. Stop for approval.
+5. After approval, generate per-module prompt files that can be handed to an AI implementer and that align with this repo's existing feature workflow.
+6. Maintain persistent implementation memory in `project-memory/core-memory.md` as each module is completed.
+
+## When to trigger
+
+- User asks to "architect", "break down", "plan", "design", or "phase" a feature.
+- The work spans multiple areas such as `src/app`, `src/views`, `src/components`, `src/services`, `src/hooks`, `src/utils`, or `src/app/api`.
+- You need to understand existing repo patterns before proposing changes.
+- The user wants a module-by-module implementation plan for a new feature, enhancement, or significant refactor.
+
+## Output locations
+
+All outputs go under **`Documentation/features/<feature_name>/`**. Create that folder when generating the first artifact for a feature.
+
+| File | Purpose |
+|------|---------|
+| `Documentation/features/<feature_name>/<FEATURE_NAME>_ARCHITECTURE.md` | Master architecture plan with scope, modules, dependencies, implementation order, and file inventory |
+| `Documentation/features/<feature_name>/MODULE_<N>_<MODULE_NAME>.md` | Per-module implementation prompt file, generated only after plan approval |
+
+Naming rules:
+
+- `<FEATURE_NAME>`: `UPPER_SNAKE_CASE` such as `PDF_EXPORT_QUEUE` or `BRAND_AUDIT_FILTERS`
+- `<feature_name>`: `snake_case` such as `pdf_export_queue` or `brand_audit_filters`
+- `<MODULE_NAME>`: short `UPPER_SNAKE_CASE` label such as `API_ROUTE`, `VIEW_STATE`, `PDF_WIDGET`
+
+## Expected behavior
+
+This skill is intentionally two-stage:
+
+1. First run: create only the master architecture plan in `Documentation/features/<feature_name>/<FEATURE_NAME>_ARCHITECTURE.md`
+2. Wait for explicit approval
+3. Second run after approval: generate multiple prompt files, one per module, under `Documentation/features/<feature_name>/`
+
+If you only see a single architecture document after the first run, that is correct behavior, not a failure.
+
+---
+
+## Phase 0 - Prerequisites (HARD STOP)
+
+> Goal: confirm project-memory artifacts exist before doing any work. This skill is grounded in those documents and cannot produce a useful plan without them.
+
+Check that **all** of these files exist:
+
+- `project-memory/constitution.md`
+- `project-memory/repo-map.md`
+- `project-memory/auth-model.md`
+- `project-memory/quality-playbook.md`
+- `project-memory/core-memory.md`
+
+If **any** are missing, STOP immediately. Do not proceed to Phase 1. Do not write a partial plan. Respond to the user exactly with:
+
+> ⚠️  `/architect` requires the `project-memory/` artifacts to ground the plan in this project's actual rules, architecture, and history. The following files are missing:
+>
+> - [list each missing file]
+>
+> Please run `/create-blueprint all` first (or `/create-blueprint <artifact>` for individual ones), then re-invoke `/architect <your feature>`.
+
+Only continue to Phase 1 once every file above is present.
+
+---
+
+## Phase 1 - Research and discovery
+
+> Goal: understand the current codebase structure and constraints before designing modules.
+
+### 1.1 Read foundation docs first
+
+Read these in order:
+
+1. `project-memory/constitution.md`
+2. `project-memory/repo-map.md`
+3. `project-memory/auth-model.md`
+4. `project-memory/quality-playbook.md`
+5. `project-memory/core-memory.md`
+6. `.agent/workflows/build-feature-react.workflow.md`
+7. `.agent/skills/feature-workflow/SKILL.md`
+8. `.agent/templates/FEATURE_PLAN.md`
+9. `.agent/templates/REVIEW_REPORT.md`
+10. `.agent/templates/TEST_PLAN.md`
+
+These files define the repo's non-negotiable process and where code belongs.
+
+If `project-memory/core-memory.md` does not exist yet, create it before finalizing the first architecture plan that will use this skill.
+
+### 1.2 Map the existing architecture
+
+Before proposing modules, inspect the actual code paths involved in the feature and note existing patterns.
+
+Always identify:
+
+- Route entry points in `src/app/**`
+- Feature views in `src/views/**`
+- Shared UI in `src/components/**`
+- Hooks in `src/hooks/**`
+- Service/data logic in `src/services/**`
+- Shared helpers in `src/utils/**`
+- Config and contracts in `src/configs/**` and `src/types/**`
+- Any API/BFF handlers in `src/app/api/**`
+- Auth-sensitive touchpoints in:
+  - `src/contexts/authContext.tsx`
+  - `src/utils/auth.ts`
+  - `src/configs/authConfig.ts`
+  - `src/types/auth.ts`
+
+Trace the real flow for the feature area. Typical shapes in this repo are:
+
+```text
+page.tsx -> view component -> hooks/selectors -> service -> API route -> external API
+```
+
+or
+
+```text
+page.tsx -> view component -> shared components/dialogs -> service/utils -> local state/auth context
+```
+
+### 1.3 Reuse hunting via repo-map
+
+Before proposing any new file, actively cross-reference `project-memory/repo-map.md` against the feature domain to find reuse candidates. This is the primary reuse check — the repo-map is curated and faster than a broad graph search.
+
+Steps:
+
+1. Re-read the relevant sections of `project-memory/repo-map.md` with the feature in mind (components, hooks, services, utils, types).
+2. List every existing entry that overlaps with what the feature needs.
+3. For each candidate, use `query_graph` (callers_of / callees_of / imports_of) or `get_impact_radius` to understand what it already does and who uses it — confirm it is safe to extend or reuse.
+4. For any proposed new file, write an explicit justification: "checked repo-map sections X and Y; nothing covers this because…". If you cannot write that justification, do not propose the new file.
+
+The goal is that every module in the plan preferentially extends or reuses existing code. New files are the last resort, not the default.
+
+### 1.4 Capture existing repo patterns
+
+Document the patterns that the new design must follow:
+
+- Keep `page.tsx` files thin and compositional.
+- Move heavy logic into `src/views/**`, `src/services/**`, `src/hooks/**`, or focused helpers.
+- Prefer shared derivations/selectors over repeated `filter/map/sort` chains.
+- Do not duplicate auth logic or cookie contracts.
+- Respect server/client boundaries between client components, server routes, and secret-bearing code.
+- Tighten service and transform types instead of introducing `any`.
+
+### 1.5 Identify integration points
+
+For the requested feature, explicitly note:
+
+- Existing files and modules that are closest to the requested behavior
+- Shared services or utilities to reuse
+- Data contracts and types that must be reused or extended
+- API routes or external services that are affected
+- Auth or permission implications
+- Performance-sensitive transforms or rendering paths
+- Whether tests should be unit, integration, manual, or mixed
+- What must be persisted into `project-memory/core-memory.md` after each module lands
+
+### 1.6 Capture scope decisions
+
+Before designing modules, write down:
+
+- In scope
+- Out of scope
+- Assumptions
+- Open questions
+
+If the request is ambiguous, ask clarifying questions before writing the plan.
+
+---
+
+## Phase 2 - Module decomposition
+
+> Goal: split the feature into small modules with clear ownership and dependencies.
+
+### 2.1 Decomposition principles
+
+Apply these rules:
+
+1. Single responsibility per module.
+2. Each module should be mergeable with minimal risk.
+3. Dependencies must be explicit.
+4. Each module should provide testable value.
+5. Prefer smaller modules if a module feels too broad.
+6. Follow existing repo boundaries instead of inventing new layers.
+7. Keep pages thin; avoid modules that push business logic into route/page files.
+8. **Reuse over create**: before proposing a new file, confirm via repo-map.md that nothing equivalent exists. Prefer extending an existing hook, service, or component. A new file must be justified explicitly.
+9. **Deletion safety**: before proposing to delete any file, run `get_impact_radius` on it. List every active caller and dependent. If callers exist, the module must include a migration path for each one before the deletion is permitted. Never propose a deletion without this check.
+
+### 2.2 Valid module shapes in this repo
+
+Common module types for this include:
+
+- Route composition module
+- Feature view/container module
+- Shared component or dialog module
+- Hook/state orchestration module
+- Service/API integration module
+- Shared transform/helper module
+- Auth/permission adjustment module
+- Testing/verification module
+
+Use the smallest combination that fits the actual request.
+
+### 2.3 For each module, define
+
+Every module section in the architecture plan must include these fields. Write them precisely — this content is extracted verbatim into the per-module implementation prompts, so prose rationale and justification notes belong in the architecture plan preamble, not inside the module sections.
+
+| Section | Content |
+|---------|---------|
+| Goal | One-sentence outcome — what the module produces, not why |
+| Depends on | Prior module numbers or `-` |
+| Estimated effort | Rough time range |
+| Key deliverables | Main outcomes as a short bullet list |
+| New files | Table: `File \| Purpose` — one-line purpose per file; repo-map justification as a footnote in the plan, not in the table cell |
+| Changed files | Table: `File \| Anchor symbol \| Exact change` — anchor is the existing function/type/component to locate; exact change is the specific mutation ("add X param", "extend return type with Y", "insert case Z") |
+| Deleted files | Table: `File \| Active callers (get_impact_radius) \| Pre-condition for deletion` |
+| Architecture | Short ASCII diagram for non-trivial call chains only; omit if the file changes are self-explanatory |
+| Contracts | Actual TypeScript — interfaces, function signatures, prop types, route payload shapes. No prose descriptions. |
+| Implementation notes | Module-specific edge cases or constraints only — nothing that restates constitution.md or quality-playbook.md |
+| Auth / permissions | Specific auth implications for this module, or omit if none |
+| Verification | Exact test commands with flags and paths; specific manual steps |
+| Memory update | Exact sentences for core-memory; exact repo-map edits (table rows, section) if this module adds routes/services/patterns |
+
+### 2.4 Use simple architecture diagrams when helpful
+
+Prefer short ASCII diagrams for non-trivial modules.
+
+Examples:
+
+```text
+App Route
+  -> Feature View
+    -> Shared Components
+    -> Hook / selector
+      -> Service
+        -> API route
+          -> External API
+```
+
+```text
+Dialog UI
+  -> local form state
+  -> submit handler
+    -> service transform
+      -> API request
+        -> response typing
+          -> view refresh
+```
+
+---
+
+## Phase 3 - Dependency ordering and implementation sequence
+
+> Goal: produce a safe serial order for implementation.
+
+### 3.1 Build the dependency graph
+
+Identify:
+
+- standalone modules that can ship first
+- modules that unblock others
+- modules that should remain behind a flag or guarded rollout
+- modules that should be grouped in one merge because of tight contract coupling
+
+### 3.2 Define the implementation order
+
+Present the order as a numbered chain, for example:
+
+```text
+1. Shared contracts/helpers
+   |
+2. Service/API integration
+   |
+3. Feature hook/state orchestration
+   |
+4. View/component wiring
+   |
+5. Tests and final verification
+```
+
+### 3.3 Note merge guidance
+
+Call out:
+
+- safe standalone modules
+- coupled modules that should land together
+- risky modules that need extra verification
+- auth-sensitive modules that require `auth-and-permissions`
+
+---
+
+## Phase 4 - Produce the architecture plan and stop for approval
+
+> Goal: create one approved master plan before generating prompts or code.
+
+### 4.1 Save location
+
+Save the master plan to:
+
+`Documentation/features/<feature_name>/<FEATURE_NAME>_ARCHITECTURE.md`
+
+### 4.2 Required document structure
+
+Use this structure:
+
+```markdown
+# [Feature Name] Architecture Plan
+
+[Brief description of the requested enhancement and intended outcome.]
+
+## Scope decisions
+
+### In scope
+- ...
+
+### Out of scope
+- ...
+
+### Assumptions
+- ...
+
+### Open questions
+- ...
+
+## Memory strategy
+
+- Memory document: `project-memory/core-memory.md`
+- What to append after each module:
+  - completed status
+  - files added/changed
+  - key architectural decisions
+  - auth implications
+  - tests run and gaps
+  - notes for the next module
+- Repo map: when the feature adds new API routes, services, hooks, or reusable patterns, update `project-memory/repo-map.md` (tables or placement notes) so the map stays the single source of truth.
+
+## Relevant codebase study
+
+- `path/to/file` - why it matters
+- `path/to/file` - why it matters
+
+## Module overview
+
+| # | Module | Depends On | Estimated Effort | Key Deliverables |
+|---|--------|------------|------------------|------------------|
+| 1 | ...    | -          | ...              | ...              |
+
+## Module 1 - [Name]
+
+**Goal**: [one sentence — what this module produces]
+
+**Depends on**: [module numbers or `-`]
+
+**Estimated effort**: ...
+
+**Key deliverables**: ...
+
+### New files
+| File | Purpose |
+|------|---------|
+| ... | [one-line purpose — repo-map justification as a footnote below this table if needed] |
+
+### Changed files
+| File | Anchor symbol | Exact change |
+|------|---------------|--------------|
+| ... | `existingSymbol` | [specific mutation: "add X param", "extend return type with Y", "insert case Z"] |
+
+### Deleted files
+| File | Active callers (from get_impact_radius) | Pre-condition for deletion |
+|------|-----------------------------------------|---------------------------|
+| ... | none | ... |
+
+### Architecture
+[Short ASCII diagram only if the call chain is non-obvious. Omit if the file changes are self-explanatory.]
+
+### Contracts
+[Actual TypeScript — interfaces, function signatures, prop types, route payloads. No prose.]
+
+```typescript
+// replace with real types for this module
+```
+
+### Implementation notes
+[Module-specific edge cases or constraints only. Omit anything already covered by constitution.md or quality-playbook.md.]
+
+### Auth / permissions
+[Specific auth implications, or omit if none.]
+
+### Verification
+- `[exact test command with flags and paths]`
+- Manual: [specific UI action or API call]
+
+### Memory update
+- **core-memory**: [exact sentences to append]
+- **repo-map**: [exact table rows or section edits, or omit if no new routes/services/patterns]
+
+## Implementation order
+
+[dependency chain]
+
+## Merge guidance
+
+- ...
+
+## Test strategy
+
+- Unit:
+- Integration:
+- Manual:
+
+## Files inventory
+
+| File | Action | Module | Notes |
+|------|--------|--------|-------|
+| ...  | Create | M1 | repo-map justification |
+| ...  | Update | M2 | |
+| ...  | Delete | M3 | callers verified zero via get_impact_radius |
+```
+
+### 4.3 Hard stop
+
+After creating `Documentation/features/<feature_name>/<FEATURE_NAME>_ARCHITECTURE.md`:
+
+- Present the plan to the user.
+- Stop and wait for explicit approval.
+- Do not generate module prompt files yet.
+- Do not write application code yet.
+
+If the user wants changes, update the architecture plan and re-present it.
+
+---
+
+## Phase 5 - Generate per-module implementation prompts
+
+> Goal: after approval, generate one prompt file per module that a downstream AI can execute safely.
+
+### 5.1 Trigger
+
+Only do this after the user explicitly approves the architecture plan from Phase 4.
+
+### 5.2 Output files
+
+For each approved module `N`, create:
+
+`Documentation/features/<feature_name>/MODULE_<N>_<MODULE_NAME>.md`
+
+Example:
+
+```text
+Documentation/features/pdf_export_queue/MODULE_1_SHARED_TYPES.md
+Documentation/features/pdf_export_queue/MODULE_2_API_ROUTE.md
+Documentation/features/pdf_export_queue/MODULE_3_QUEUE_WIDGET.md
+Documentation/features/pdf_export_queue/MODULE_4_TESTS.md
+```
+
+### 5.3 Prompt file format
+
+Each file should follow this format:
+
+```markdown
+You are implementing a feature module in the this repo (Next.js App Router, React, TypeScript). Follow this process exactly.
+
+First, read these files in order:
+1. `project-memory/constitution.md`
+2. `project-memory/repo-map.md`
+3. `project-memory/auth-model.md`
+4. `project-memory/quality-playbook.md`
+5. `project-memory/core-memory.md`
+6. `.agent/workflows/build-feature-react.workflow.md`
+7. `.agent/skills/feature-workflow/SKILL.md`
+8. `.agent/templates/FEATURE_PLAN.md`
+9. `.agent/templates/REVIEW_REPORT.md`
+10. `.agent/templates/TEST_PLAN.md`
+11. `Documentation/features/<feature_name>/<FEATURE_NAME>_ARCHITECTURE.md`
+
+Artifact paths for this feature (use these; do not use .agent/plans or .agent/docs):
+- Feature plan: `Documentation/features/<feature_name>/FEATURE_PLAN.md`
+- Test plan: `Documentation/features/<feature_name>/TEST_PLAN.md`
+- Review report: `Documentation/reports/REVIEW_REPORT.md`
+
+Hard rules:
+- No coding before plan approval.
+- Implement only the approved scope for this module.
+- Keep `page.tsx` files thin.
+- Reuse existing auth surfaces; do not create parallel auth logic.
+- Respect server/client boundaries.
+- Reuse shared derivations/helpers instead of duplicating transforms.
+- Before creating any new file, cross-reference `project-memory/repo-map.md` for existing alternatives; only create if none exists and document why.
+- Before deleting any file, run `get_impact_radius` to confirm zero active callers, or execute the migration path specified in the architecture plan before removing the file.
+- After implementation, run `.agent/skills/react-quality-review/SKILL.md` and fix all findings.
+- If the module touches auth-sensitive code or protected routes, also run `.agent/skills/auth-and-permissions/SKILL.md`.
+- Run tests and verification before finalizing: run the test suite (e.g. `npm run test`) for affected areas; fix all failures before updating memory or moving on.
+- Update `project-memory/core-memory.md` after implementing the module and after tests/review are complete.
+- If this module adds new API routes, services, hooks, or reusable patterns, update `project-memory/repo-map.md` (relevant tables or placement notes).
+- Do not finalize development until required tests and verification commands have been run and recorded.
+
+---
+
+## Module <N> - <Module Name>
+
+**Goal**: [one sentence — what this module produces]
+
+**Depends on**: [module numbers or `-`]
+
+### Files to create
+
+| File | Purpose |
+|------|---------|
+| `path/to/new/file.ts` | [what it exports and why no equivalent exists in repo-map] |
+
+### Files to modify
+
+| File | Anchor symbol | Exact change |
+|------|---------------|--------------|
+| `path/to/file.ts` | `existingFunctionOrType` | [add / extend / replace — be specific: "add `newParam: Type` to signature", "extend return type with `NewField`", "insert case for `X` in switch"] |
+
+### Files to delete
+
+| File | Pre-condition |
+|------|--------------|
+| `path/to/file.ts` | [only after callers in `other/file.ts` are migrated to `replacementSymbol`] |
+
+### Contracts
+
+[Actual TypeScript — interfaces, function signatures, prop types, route payloads. No prose descriptions — write the real types.]
+
+```typescript
+// example — replace with actual contracts for this module
+export interface ExampleType {
+  id: string;
+  name: string;
+}
+
+export function exampleFn(id: string): Promise<ExampleType>
+```
+
+### Data flow
+
+[Short ASCII diagram only if the call chain is non-obvious for this module. Omit if the file changes above make the flow self-evident.]
+
+### Auth / permissions
+
+[Only include if this module touches auth-sensitive code or protected routes. Omit otherwise.]
+
+### Verification
+
+- `[exact test command]` — [what it covers]
+- Manual: [specific UI action or API call to confirm the module works end-to-end]
+
+### Memory update
+
+- **core-memory**: [exact facts to append — completed status, files added/changed, key decisions, test gaps]
+- **repo-map**: [exact table rows or section edits to add — only if this module introduces new routes, services, hooks, or reusable patterns; omit otherwise]
+
+---
+
+## Required planning output
+
+Fill `Documentation/features/<feature_name>/FEATURE_PLAN.md` with:
+1. Requirement clarification
+2. Codebase study
+3. Detailed plan
+4. Implementation order
+
+## Quality and testing output
+
+- Fill `Documentation/reports/REVIEW_REPORT.md`
+- Fill `Documentation/features/<feature_name>/TEST_PLAN.md`
+- Add or update the tests required by this module
+- Run the test suite (e.g. `npm run test`) for affected areas; record commands and results in TEST_PLAN; fix failures before finalizing
+- Append a completed module entry to `project-memory/core-memory.md`
+- If the module added new routes, services, or patterns, update `project-memory/repo-map.md` accordingly
+```
+
+### 5.4 Content rules for module prompt files
+
+When generating module prompt files, extract only what the implementing agent needs to act — not to understand the architecture decision. Concretely:
+
+1. **Goal**: one sentence, outcome-focused. Drop all rationale.
+2. **Files to create**: exact paths only. Drop repo-map justification prose (that was for the architecture review). A one-line purpose is enough.
+3. **Files to modify**: must include the anchor symbol (the existing function, type, or component to locate) and the exact change — "add X", "extend Y to include Z", "replace W with V". Never just "update this file to support the feature."
+4. **Files to delete**: keep only pre-conditions for safe deletion. Drop the impact-radius analysis (already done in the architecture plan).
+5. **Contracts**: write actual TypeScript — interfaces, function signatures, prop types, route payload shapes. Never describe them in prose. These are the authoritative types the agent must implement.
+6. **Data flow**: include only if the call chain across files is non-obvious. A single-file module rarely needs this. Keep it to the specific path for this module, not the whole feature.
+7. **Implementation notes**: omit entirely unless there is a module-specific edge case or constraint that is NOT already covered by `constitution.md` or `quality-playbook.md`. Generic reminders ("keep pages thin", "respect server/client boundary") belong in Hard rules, not here.
+8. **Auth / permissions**: include only if this specific module touches auth-sensitive code. Not a boilerplate flag.
+9. **Verification**: exact commands with flags, not generic `npm run test`. Specify which paths/suites to run.
+10. **Memory update**: exact sentences to append to core-memory and exact repo-map edits (table rows, section placement). No vague "document what changed."
+
+### 5.5 Confirmation to user
+
+After generating prompt files, report:
+
+- all created file paths
+- which module each file covers
+- recommended implementation order
+
+---
+
+## Quality gates
+
+Before finalizing the architecture plan, verify:
+
+- [ ] The relevant foundation docs were read first.
+- [ ] Scope, assumptions, and open questions are explicit.
+- [ ] Existing repo patterns were studied before proposing changes.
+- [ ] `project-memory/repo-map.md` was cross-referenced against the feature domain to identify reuse candidates before proposing new files.
+- [ ] Every proposed new file includes an explicit repo-map justification confirming no equivalent exists.
+- [ ] Every proposed deletion has had `get_impact_radius` run; active callers are listed and either zeroed out or a migration path is specified.
+- [ ] Each module has explicit dependencies.
+- [ ] Each module includes verification steps.
+- [ ] Server/client boundaries are respected.
+- [ ] Auth-sensitive work is identified.
+- [ ] Page files remain thin in the proposed design.
+- [ ] Shared derivations/helpers are preferred over duplicate transforms.
+- [ ] The files inventory covers every proposed file change (create, update, delete) with notes.
+- [ ] The implementation order matches the dependency graph.
+- [ ] Each module defines what must be written to `project-memory/core-memory.md`.
+- [ ] When the feature adds new routes, services, or patterns, the plan (or Memory update) states that `project-memory/repo-map.md` must be updated.
+
+---
+
+## Chaining with other skills
+
+This skill designs the implementation. It does not replace the existing execution workflow.
+
+After planning:
+
+1. Use `.agent/skills/feature-workflow/SKILL.md` to implement each approved module.
+2. Use `.agent/skills/auth-and-permissions/SKILL.md` for auth-sensitive modules.
+3. Use `.agent/skills/react-quality-review/SKILL.md` after implementation.
+
+The generated module prompts should make downstream implementation safer, smaller in scope, and consistent with the repo's required plan -> approval -> implementation -> review -> test sequence, with `project-memory/core-memory.md` updated after every implemented module.

package/.agent/frontend/skills/auth-and-permissions/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: auth-and-permissions
+description: Add or modify auth-sensitive routes/pages without breaking the current Keystone/Prism auth model.
+when_to_use:
+  - Creating or changing pages under `src/app/[lang]/(dashboard)/(private)/`
+  - Adding permission-gated UI behavior
+  - Updating auth-sensitive API routes under `src/app/api/**`
+references:
+  - project-memory/repo-map.md
+  - project-memory/auth-model.md
+  - project-memory/constitution.md
+  - src/contexts/authContext.tsx
+  - src/utils/auth.ts
+  - src/configs/authConfig.ts
+  - src/types/auth.ts
+---
+
+# Auth and Permissions Skill
+
+## Steps
+
+1. Read `project-memory/repo-map.md` and `project-memory/auth-model.md` before touching auth-sensitive code.
+2. For private pages, follow the existing route layout under `src/app/[lang]/(dashboard)/(private)/...`.
+3. For UI permission gating, consume auth state from `useAuth()` in `src/contexts/authContext.tsx`.
+4. Reuse auth helpers from `src/utils/auth.ts` for cookie/token/header behavior; do not duplicate logic.
+5. Keep cookie key contracts centralized in `src/configs/authConfig.ts`.
+6. Extend permission typing in `src/types/auth.ts` when introducing new permission keys.
+7. Add or update tests for authorized/unauthorized behavior where relevant.
+
+## Non-Negotiable Checklist (must all be true)
+
+- [ ] Page/component auth state comes from `useAuth()` in `src/contexts/authContext.tsx`.
+- [ ] Cookie and token handling reuses `src/utils/auth.ts` helpers or approved extensions.
+- [ ] Cookie key usage remains centralized in `src/configs/authConfig.ts`.
+- [ ] No duplicate auth helpers were added outside the canonical auth modules.
+- [ ] Access tests cover both authorized and unauthorized outcomes.
+
+## Deliverable
+
+For each auth-sensitive change, include a short note in PR/plan stating:
+- route path changed
+- permission key(s) used from `src/types/auth.ts` / permission checks
+- where `useAuth()` and auth helpers enforce behavior