@erclx/aitk 0.8.0

package/docs/zshrc-aliases.md

@@ -0,0 +1,65 @@
+---
+title: Zshrc aliases for Claude Code
+description: Shell aliases that shorten common Claude Code invocations
+category: Workflow
+---
+
+# Zshrc aliases for Claude Code
+
+Claude Code auto-discovers the toolkit plugin from `claude/.claude-plugin/plugin.json` when run inside the toolkit repository. Outside the toolkit, that discovery does not fire, so a separate set of aliases bakes in `--plugin-dir` explicitly. Two parallel sets cover both cases.
+
+## The aliases
+
+`bun run bootstrap` installs this block. It owns the canonical copy in `scripts/core/bootstrap.sh`, appends it to `~/.zshrc` wrapped in the two marker comments below, and sets `TOOLKIT` to the cloned path. The markers are how a re-run recognizes its own block and skips.
+
+A block installed by hand before the managed one has no markers. Bootstrap detects that case through the `alias clp=` line instead, warns, and leaves the block untouched rather than appending a second copy. To switch over, delete the hand-rolled block and re-run the bootstrap.
+
+```zsh
+# >>> aitk aliases >>>
+TOOLKIT="/path/to/toolkit"
+
+alias cl='claude'
+alias clr='cl -r'
+alias clc='cl -c'
+alias clw='cl -w'
+alias cls='cl --model sonnet'
+
+alias clp='claude --plugin-dir $TOOLKIT/claude'
+alias clpc='clp -c'
+alias clps='clp --model sonnet'
+# <<< aitk aliases <<<
+```
+
+The block sits after any `PATH` mutations and the `claude` CLI install. Zsh expands aliases recursively on the first word, so `clr`, `clc`, `clw`, and `cls` inherit their base through `cl`, and `clpc` and `clps` inherit `--plugin-dir` through `clp`. `$TOOLKIT` expands at invocation time, so updating the variable and re-sourcing reroutes all `clp` calls without touching the alias definitions.
+
+## What each one does
+
+`cl` through `cls` carry no explicit plugin dir. Use them inside the toolkit repository, where Claude Code auto-discovers the plugin from `claude/.claude-plugin/plugin.json`. Loading `--plugin-dir` on top of auto-discovery registers every skill twice and produces duplicate entries in the slash command list.
+
+- `cl`: plain session in the current directory
+- `clr`: opens the `/resume` picker scoped to the current directory. Trailing arguments filter by name. `clr auth` limits results to sessions containing "auth".
+- `clc`: jumps straight into the most recent session for the current directory. No picker. Faster than `clr` when the terminal closed and you want back into the same session.
+- `clw`: creates a worktree under `.claude/worktrees/<name>/` on a fresh branch and starts a Claude Code session in it. Pass the worktree name as the trailing arg: `clw feat-auth`.
+- `cls`: pins the session to Sonnet instead of the default Opus. Use for routine work where Opus cost is not justified.
+
+`clp`, `clpc`, and `clps` bake in `--plugin-dir`. Use them outside the toolkit repository, where auto-discovery does not fire.
+
+- `clp`: session with the toolkit plugin loaded explicitly
+- `clpc`: jumps straight into the most recent session for the current directory with the plugin loaded. The `clp` mirror of `clc`.
+- `clps`: `clp` pinned to Sonnet
+
+## When to use which
+
+Use `cl` by default when working in the toolkit repository. Auto-discovery loads the plugin and the two-key alias keeps it short.
+
+Use `clp` in any other repository where you want the toolkit skills available. Without the flag, those repos do not load the plugin.
+
+Use `cls` or `clps` to save Opus usage on routine sessions. Switch mid-session with `/model` to avoid restarting.
+
+Use `clw <name>` for features that will take more than one session. A worktree isolates the branch, the transcripts, and the `/resume` history. See [Claude Code and git worktrees](../wiki/claude-worktrees.md) for fan-out rules.
+
+Use `clc` to resume the last session without a picker. Use `clr` when you have several sessions and need to pick by name or recency. Outside the toolkit repo, `clpc` is the same shortcut as `clc` with the plugin loaded.
+
+## Why not a function
+
+A function with subcommand dispatch (`cl r`, `cl c`, `cl w foo`) was considered and rejected. It loses shell completion and adds a layer of indirection. Separate aliases are self-contained and the shared `cl`/`clp` prefixes make them easy to recall.

package/governance/rules/claude/500-prose.md

@@ -0,0 +1,12 @@
+---
+description: Route markdown edits to the prose standard for voice, structure, formatting, and punctuation
+paths:
+  - '**/*.md'
+---
+
+# Markdown prose standards
+
+## Authority
+
+- Follow `.claude/standards/prose.md` for all prose: voice, structure, formatting, language, and banned punctuation. It is the single source.
+- Read it before a substantial prose edit. Do not work the bans from memory.

package/governance/rules/claude/510-context.md

@@ -0,0 +1,16 @@
+---
+description: Route .claude/context edits to the context-entry standard and the consult-first workflow
+paths:
+  - '.claude/context/**'
+---
+
+# Context entry standards
+
+## Before editing
+
+- Before non-trivial work in a domain, read its `.claude/context/<domain>.md` entry. Use `.claude/context/index.md` to find it.
+- Leave the entry conforming when work in its domain changes what it describes.
+
+## Authority
+
+- Follow `.claude/standards/context.md` for entry shape: frontmatter, sections, length, and what goes in. It is the single source.

package/governance/rules/claude/520-wireframes.md

@@ -0,0 +1,12 @@
+---
+description: Route .claude/wireframes edits to the wireframe standard for layout and interaction intent
+paths:
+  - '.claude/wireframes/**'
+---
+
+# Wireframe standards
+
+## Authority
+
+- Follow `.claude/standards/wireframes.md` for layout and interaction intent: ASCII layout, region labels, variants, copy, and what moves to `.claude/context/`. It is the single source.
+- A wireframe carries layout and intent, not implementation. Read the standard before adding or revising a surface.

package/governance/rules/claude/530-requirements.md

@@ -0,0 +1,11 @@
+---
+description: Route .claude/REQUIREMENTS.md edits to the requirements standard for product scope and goals
+paths:
+  - '.claude/REQUIREMENTS.md'
+---
+
+# Requirements standards
+
+## Authority
+
+- Follow `.claude/standards/requirements.md` for what belongs in the problem, goals, non-goals, MVP features, tech stack, and constraints. It is the single source.

package/governance/rules/claude/540-architecture.md

@@ -0,0 +1,11 @@
+---
+description: Route .claude/ARCHITECTURE.md edits to the architecture standard for system decisions and risks
+paths:
+  - '.claude/ARCHITECTURE.md'
+---
+
+# Architecture standards
+
+## Authority
+
+- Follow `.claude/standards/architecture.md` for the overview, named decision entries, and risks. It is the single source.

package/governance/rules/claude/550-design.md

@@ -0,0 +1,11 @@
+---
+description: Route .claude/DESIGN.md edits to the design standard for visual intent and token tables
+paths:
+  - '.claude/DESIGN.md'
+---
+
+# Design standards
+
+## Authority
+
+- Follow `.claude/standards/design.md` for visual intent, the token tables, and the render contract. It is the single source.

package/governance/rules/claude/555-tasks.md

@@ -0,0 +1,12 @@
+---
+description: Route .claude/tasks/ edits to the tasks standard for filenames, frontmatter, and task file format
+paths:
+  - '.claude/tasks/**'
+---
+
+# Tasks standards
+
+## Authority
+
+- Follow `.claude/standards/tasks.md` for filenames, frontmatter, what belongs, and the task file format. It is the single source.
+- Never hand-edit `.claude/tasks/index.md`. A hook regenerates it from sibling frontmatter.

package/governance/rules/claude/560-diagrams.md

@@ -0,0 +1,11 @@
+---
+description: Route .claude/DIAGRAMS.md edits to the diagrams standard for Mermaid conventions
+paths:
+  - '.claude/DIAGRAMS.md'
+---
+
+# Diagrams standards
+
+## Authority
+
+- Follow `.claude/standards/diagrams.md` for Mermaid diagram layout, labeling, and narrative. It is the single source.

package/governance/rules/claude/570-skill.md

@@ -0,0 +1,18 @@
+---
+description: Route skill edits to the authoring standard and the requirement consult-first workflow
+paths:
+  - '.claude/skills/**/SKILL.md'
+  - 'claude/skills/**/SKILL.md'
+  - '.claude/skills/**/REQUIREMENT.md'
+  - 'claude/skills/**/REQUIREMENT.md'
+---
+
+# Skill standards
+
+## Before editing
+
+- Read the skill's sibling `REQUIREMENT.md` when one exists. If the change closes no gap it states, change the requirement first or drop the change.
+
+## Authority
+
+- Follow `.claude/standards/skill.md` for skill structure, frontmatter fields, and invocation rules. It is the single source.

package/governance/rules/claude/580-readme.md

@@ -0,0 +1,11 @@
+---
+description: Route README edits to the readme standard for structure, sections, and content conventions
+paths:
+  - '**/README.md'
+---
+
+# README standards
+
+## Authority
+
+- Follow `.claude/standards/readme.md` for structure, required and optional sections, heading hierarchy, and what to link out rather than inline. It is the single source.

package/governance/rules/claude/590-rule-authoring.md

@@ -0,0 +1,12 @@
+---
+description: Enforce frontmatter, body shape, and voice for governance rule files
+paths:
+  - '.claude/rules/**/*.md'
+---
+
+# Rule authoring standards
+
+## Authority
+
+- Follow `.claude/standards/rule.md` for rule frontmatter, body shape, and voice. It is the single source.
+- Read it before writing or editing a rule. Do not work the shape from memory.

package/governance/rules/core/000-constitution.md

@@ -0,0 +1,30 @@
+---
+description: Define senior architect persona and core philosophy
+---
+
+# Role persona
+
+You are a Senior Principal Architect.
+Your primary directive is to maintain long-term system health over short-term convenience.
+
+## Readability and simplicity
+
+- Optimize for readability. Code is read far more than it is written.
+- Code must be self-documenting through clear naming and explicit structure.
+- Comments are permitted ONLY to explain intent, never logic.
+- Prefer the simplest implementation that satisfies the requirement (KISS).
+
+## Design philosophy
+
+- Implement only the functionality required for the immediate task (YAGNI).
+- Extract shared logic into single-purpose utilities. Never duplicate behavior across modules (DRY).
+- Each function, module, and component should have a single reason to change (SRP).
+- Apply SRP to directories: once a folder mixes distinct roles and grows past a handful of files, split it into subfolders by role.
+- Favor composition over inheritance.
+- Prioritize native platform capabilities over third-party libraries.
+
+## Data integrity
+
+- Favor explicit behavior over implicit magic or conventions.
+- Ensure data and configuration reside in designated Single Source of Truth locations.
+- Treat data as immutable unless mutation is explicitly required.

package/governance/rules/core/010-testing.md

@@ -0,0 +1,35 @@
+---
+description: Enforce universal testing standards and best practices
+---
+
+# Testing standards
+
+## Test structure
+
+- Structure tests using the Arrange, Act, Assert (AAA) pattern.
+- Each test should verify a single behavior.
+- Do not use conditional logic or loops within test bodies.
+
+## Test focus
+
+- Test user-visible behavior rather than implementation details.
+- Do not test private functions or internal state directly.
+- Cover critical paths and edge cases.
+- Do not target arbitrary coverage percentages.
+
+## Organization and isolation
+
+- Group related tests using the framework's nesting mechanism.
+- Keep nesting shallow (max 2 levels).
+- Ensure tests are independent with no shared side effects.
+- Clean up side effects and restore state after each test.
+
+## Test data and async
+
+- Use factory functions or builders for test data over inline object literals.
+- Always await async operations.
+- Do not fire-and-forget promises in tests.
+
+## Verification
+
+- Do not use snapshot testing for verification.

package/governance/rules/core/020-concurrency.md

@@ -0,0 +1,22 @@
+---
+description: Enforce safe concurrency and async operation patterns
+---
+
+# Concurrency standards
+
+## Async lifecycle
+
+- Make async operations cancellable. Clean up on scope exit or caller cancellation.
+- Coordinate dependent async operations explicitly. Document execution order.
+- Set explicit timeouts on all external async operations.
+- Do not fire-and-forget async operations without cleanup handlers.
+- Batch independent async operations. Do not run them sequentially when parallelizable.
+
+## Race conditions
+
+- Do not ignore race conditions in concurrent flows.
+- Protect shared mutable state with locks, queues, or single-writer patterns.
+
+## Failure handling
+
+- Handle partial failures in batched operations independently. Do not fail the entire batch for a single error.

package/governance/rules/core/030-error-handling.md

@@ -0,0 +1,31 @@
+---
+description: Enforce consistent error handling patterns
+---
+
+# Error handling standards
+
+## Boundary validation
+
+- Validate inputs at system boundaries. Reject invalid data immediately.
+- Do not use exceptions for control flow.
+
+## Error classification
+
+- Distinguish expected failures (validation, not found) from unexpected failures (null reference, network timeout).
+- Return structured error types for recoverable failures.
+- Propagate exceptions for programmer errors.
+
+## Error propagation
+
+- Handle errors at the layer with enough context to respond meaningfully.
+- Do not catch and rethrow without adding value.
+- Do not silently ignore errors.
+
+## Error reporting
+
+- Include actionable context in error messages.
+- Never expose internal implementation details in error messages.
+
+## Retry behavior
+
+- Retry only idempotent operations with bounded attempts and backoff.

package/governance/rules/core/040-performance.md

@@ -0,0 +1,20 @@
+---
+description: Enforce performance constraints and optimization patterns
+---
+
+# Performance standards
+
+## Resource loading
+
+- Lazy load resources at architectural boundaries, not inline.
+- Do not import entire modules when subsets are sufficient.
+
+## Execution efficiency
+
+- Defer non-critical work until after primary output completes.
+- Do not fetch data inside loops.
+
+## Data handling
+
+- Paginate or stream unbounded data sets.
+- Do not optimize without measurement.

package/governance/rules/core/050-logging.md

@@ -0,0 +1,20 @@
+---
+description: Enforce structured logging and observability
+---
+
+# Logging standards
+
+## Log coverage
+
+- Log state transitions at boundaries (requests received, external calls made, errors encountered).
+- Do not log in performance-critical code paths.
+
+## Log format
+
+- Use structured formats with consistent metadata (timestamp, severity, correlation ID).
+- Emit logs at appropriate severity: critical for failures, informational for significant events.
+
+## Log safety
+
+- Do not log credentials, tokens, or personally identifiable information.
+- Log observable behavior, not implementation details.

package/governance/rules/core/060-naming.md

@@ -0,0 +1,19 @@
+---
+description: Enforce consistent naming semantics across all code
+---
+
+# Naming standards
+
+## Semantics
+
+- Prefer descriptive names over abbreviations: `getUserProfile` over `getUP`.
+- Name functions as actions describing what they do: `fetchUser`, `calculateTotal`.
+- Prefix booleans with `is`, `has`, `should`, or `can`: `isLoading`, `hasAccess`.
+- Avoid negative boolean names: `isEnabled` over `isNotDisabled`.
+- Prefix event handlers with `handle`: `handleClick`, `handleSubmit`.
+- Name collections as plurals: `users`.
+- Name items as singulars: `user`.
+
+## Test naming
+
+- Name tests with descriptive phrases that state the expected behavior.

package/governance/rules/core/070-planning.md

@@ -0,0 +1,13 @@
+---
+description: Enforce planning standards before implementation
+---
+
+# Planning standards
+
+## Planning
+
+- Analyze requests and output a numbered implementation plan before execution.
+- Challenge ambiguous or over-engineered requests before implementation.
+- Propose the simplest solution that satisfies the requirement before implementing complex patterns.
+- Write or update tests as part of every implementation plan.
+- Do not modify code without a confirmed plan.

package/governance/rules/core/080-config-comments.md

@@ -0,0 +1,22 @@
+---
+description: Keep comments terse in dotfiles, config, and workflow files
+paths:
+  - '**/.env*'
+  - '**/.gitignore'
+  - '**/.dockerignore'
+  - '**/.editorconfig'
+  - '**/Dockerfile*'
+  - '**/*.config.*'
+  - '**/*.json'
+  - '**/*.yml'
+  - '**/*.yaml'
+---
+
+# Config comment standards
+
+## Comments
+
+- Keep each comment to one short line. Do not wrap a single key in a multi-line explanation.
+- Prefer a one-word category label over a sentence for a group header.
+- Match the comment density of the surrounding file. Do not add a verbose comment next to terse ones.
+- Comment what a key does or its allowed values. Do not restate the key name.

package/governance/rules/framework/200-react.md

@@ -0,0 +1,51 @@
+---
+description: Enforce opinionated React architecture and component patterns
+paths:
+  - '**/*.tsx'
+  - '**/*.ts'
+---
+
+# React architecture standards
+
+## Export conventions
+
+- Use named exports exclusively for components and hooks.
+- Do not use default exports.
+
+## Project structure
+
+- Place domain logic in `src/features/` and restrict `src/components/` to shared UI.
+- Do not place feature-specific components in the global components folder.
+- Import environment variables only from the validated configuration module.
+
+## Component patterns
+
+- Use function declarations for components over arrow functions.
+- Define TypeScript interfaces for props immediately above the component.
+- Use `<>` shorthand for fragments unless key prop is required.
+- Use stable, unique keys for list items over array index.
+- Extract components when JSX exceeds a single responsibility.
+
+## State and effects
+
+- Encapsulate data fetching and complex effects in custom hooks.
+- Use `useMemo` for derived state over `useEffect`.
+- Do not call `setState` inside `useEffect` to sync derived state. The `react-hooks/set-state-in-effect` lint enforces this.
+- Compare the previous value during render and call `setState` from the render body when it changes, over syncing in an effect.
+- Lift the state to a parent and reset the child with a `key` prop, over running a reset effect in the child.
+- Return a sentinel (`undefined` or a `useSyncExternalStore` placeholder) from hooks that hydrate asynchronously and gate consumers on it, over running a hydration effect.
+
+## Memoization
+
+- Memoize components receiving non-primitive props with `React.memo`.
+- Use `useCallback` for handler props passed to children.
+
+## Composition and props
+
+- Avoid prop drilling beyond 2 levels. Use context or composition.
+
+## Error boundaries and Suspense
+
+- Place error boundaries at route level.
+- Place Suspense at data-fetching boundaries.
+- Do not use a single root-level error boundary as the only safety net.

package/governance/rules/framework/210-astro.md

@@ -0,0 +1,41 @@
+---
+description: Enforce astro static-first architecture with explicit island opt-in
+paths:
+  - '**/*.astro'
+  - 'src/pages/**'
+  - 'src/layouts/**'
+  - 'src/content/**'
+---
+
+# Astro standards
+
+## Static first
+
+- Write pages and components as `.astro` unless interactivity requires a framework island.
+- Do not add a framework integration until the first island needs it.
+- Prefer server-rendered content over client-fetched data.
+
+## Islands
+
+- Apply `client:*` directives on the component boundary, not on parents.
+- Prefer `client:visible` or `client:idle` over `client:load`. Use `client:load` only for above-the-fold interactivity.
+- Keep islands leaf-level. Do not wrap layout chrome in a framework component to enable nested islands.
+
+## Routing and layouts
+
+- Place routes in `src/pages/`. Use `[param].astro` for dynamic segments and `[...rest].astro` for catch-alls.
+- Extract shared chrome into `src/layouts/` and compose pages with a `<Layout>` wrapper.
+
+## Content
+
+- Use content collections in `src/content/` with a `config.ts` schema for any repeated structured content.
+- Access collection entries via `getCollection` and `getEntry` over direct file imports.
+
+## Styles and assets
+
+- Component styles are scoped by default. Use `is:global` only in layouts for reset or base styles.
+- Import images from `src/assets/` to get optimization. Use `public/` only for untouched static files.
+
+## Environment
+
+- Read environment variables via `import.meta.env`. Prefix client-exposed variables with `PUBLIC_`.

package/governance/rules/framework/220-fastapi.md

@@ -0,0 +1,43 @@
+---
+description: Enforce FastAPI router, dependency injection, and async handler patterns
+paths:
+  - '**/*.py'
+---
+
+# FastAPI standards
+
+## Project structure
+
+- Mount routes through `APIRouter` modules. Do not register handlers directly on `FastAPI()`.
+- Group routers by feature under `src/<pkg>/api/` and include them from the root app factory.
+- Use an `app_factory()` callable over a module-level `app = FastAPI()` for testability.
+
+## Handlers
+
+- Define path operations as `async def` unless the handler is purely CPU-bound.
+- Do not perform blocking I/O inside `async def`. Use async clients or `run_in_threadpool`.
+- Annotate path, query, and body parameters explicitly. Do not rely on `**kwargs`.
+- Return pydantic models and set `response_model=` on the decorator for serialization control.
+
+## Dependency injection
+
+- Express shared logic (auth, db sessions, settings) as `Depends(...)` over decorators or globals.
+- Use `Annotated[T, Depends(...)]` over default-value `Depends()` for reusable dependencies.
+- Scope db sessions per request via a generator dependency that yields then closes.
+
+## Lifespan and configuration
+
+- Use the `lifespan` context manager for startup and shutdown over deprecated `@app.on_event`.
+- Load settings via `pydantic_settings.BaseSettings`, injected through a cached dependency.
+
+## Errors
+
+- Raise `HTTPException` for client-facing errors with explicit status codes.
+- Register `@app.exception_handler` mappings for domain exceptions over per-route try/except.
+- Do not leak internal exception messages. Map to safe summaries at the boundary.
+
+## Validation and security
+
+- Validate request bodies through pydantic models. Do not parse `Request.json()` manually.
+- Apply `dependencies=[Depends(auth)]` at the router or app level for cross-cutting auth.
+- Configure CORS, trusted hosts, and HTTPS redirects through middleware, not per-route checks.

package/governance/rules/framework/230-nextjs.md

@@ -0,0 +1,48 @@
+---
+description: Enforce Next.js App Router structure, server/client boundaries, and built-in primitives
+paths:
+  - '**/*.tsx'
+  - '**/*.ts'
+---
+
+# Next.js standards
+
+## App Router structure
+
+- Use the App Router under `app/`. Do not introduce `pages/` in new code.
+- Use route segment files for their documented purpose: `page.tsx` for routes, `layout.tsx` for shared shells, `loading.tsx` for Suspense fallbacks, `error.tsx` for error boundaries, `route.ts` for HTTP handlers.
+
+## Server and client components
+
+- Default to Server Components. Add `"use client"` only when the file needs state, effects, browser APIs, or event handlers.
+- Place `"use client"` at the leaf, not at the layout. Push the boundary as deep as possible.
+- Do not import server-only modules (`fs`, db clients, secrets) from a client component. Mark server-only modules with `import "server-only"`.
+- Pass serializable props across the server/client boundary. Do not pass functions or class instances.
+
+## Data fetching
+
+- Fetch data in Server Components or Route Handlers. Do not fetch in client components when a server alternative exists.
+- Set explicit caching on `fetch`: `cache: "force-cache"`, `cache: "no-store"`, or `next: { revalidate: <seconds> }`. Do not rely on defaults.
+- Use `revalidatePath` or `revalidateTag` for invalidation over manual refetch loops.
+
+## Server Actions
+
+- Mark Server Actions with `"use server"` at the top of the file or function.
+- Validate Server Action inputs with a Zod schema before use. The client/server boundary is implicit and easy to miss.
+- Return serializable values. Do not return Response or stream objects from a Server Action.
+
+## Route handlers
+
+- Place HTTP endpoints in `app/**/route.ts`. Do not add `pages/api/`.
+- Export named methods (`GET`, `POST`, ...). Return `NextResponse` over raw `Response` for typed helpers.
+- Read params from the function signature (`{ params }`), not from the request URL.
+
+## Built-in primitives
+
+- Use `next/link` over `<a>` for internal navigation. Use `next/image` over `<img>` for raster images. Use `next/font` over manual `<link>` tags for fonts.
+- Set explicit `width` and `height` (or `fill`) on `next/image`. Do not omit dimensions.
+
+## Metadata and environment
+
+- Export `metadata` or `generateMetadata` from `layout.tsx` or `page.tsx` over manual `<head>` injection.
+- Prefix browser-exposed env vars with `NEXT_PUBLIC_`. Never read unprefixed server-only env vars from a client component.

package/governance/rules/framework/250-tailwind.md

@@ -0,0 +1,32 @@
+---
+description: Enforce Tailwind CSS v4 utility patterns, theme tokens, dark mode, and custom styles
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.html'
+  - '**/*.css'
+---
+
+# Tailwind CSS v4 standards
+
+## Theme variables
+
+- Use `@theme` for design tokens that generate utility classes.
+- Use `:root` for plain CSS variables with no utility counterpart.
+- Define dark mode color overrides in `.dark { }` at root level over `@layer base`.
+- Always pair light and dark utilities explicitly: `bg-white dark:bg-gray-900`.
+
+## Layout and spacing
+
+- Use `flex` and `grid` for all layouts.
+- Never use floats or absolute positioning for flow.
+- Use `gap-*` for sibling spacing over margins.
+- Use `size-*` over `w-* h-*` for equal dimensions.
+- Mobile-first: default styles apply to mobile. Use `sm:` and up to override.
+
+## Class application
+
+- Use `cn()` from `@/lib/utils` for all conditional class application.
+- Do not use the `!` important modifier.
+- Do not use inline `style` props for static styling. Use arbitrary values (`bg-[#316ff6]`) instead.
+- Use inline styles only for dynamic values from JS/API or to set CSS variables for utility consumption.