@geraldmaron/construct 1.0.0

package/skills/exploration/repo-map.md

@@ -0,0 +1,297 @@
+<!--
+skills/exploration/repo-map.md — Repo Exploration — Codebase Mapping Playbook — Use this skill when entering an unfamiliar codebase, doing deep investigation wo
+
+Use this skill when entering an unfamiliar codebase, doing deep investigation work, or producing a `.cx/codebase-map.md` artifact for future sessions. Agents: `
+-->
+# Repo Exploration — Codebase Mapping Playbook
+
+Use this skill when entering an unfamiliar codebase, doing deep investigation work, or producing a `.cx/codebase-map.md` artifact for future sessions.
+
+Agents: `cx-explorer` (primary), `cx-debugger` (tracing failures), `cx-architect` (architecture questions)
+
+---
+
+## Phase 1: Orient (5 minutes max)
+
+Answer these questions before reading any source files:
+
+```
+What is this project?       → README.md, package.json description, go.mod module name
+What language/runtime?      → file extensions, Dockerfile, .tool-versions, .nvmrc
+How do I run it?            → Makefile, justfile, package.json scripts, Procfile, README "Quick Start"
+How do I test it?           → CI config (.github/workflows/, .circleci/, Jenkinsfile)
+What does it depend on?     → package.json/go.mod/Cargo.toml/requirements.txt top-level deps
+How old / active is it?     → git log --oneline -10, git shortlog -sn --no-merges | head -5
+```
+
+Commands:
+```bash
+cat README.md | head -80
+cat package.json 2>/dev/null || cat go.mod 2>/dev/null || cat Cargo.toml 2>/dev/null
+ls -la
+git log --oneline -10
+git shortlog -sn --no-merges | head -5
+find . -name "Makefile" -o -name "justfile" | head -3
+```
+
+---
+
+## Phase 2: Map the Structure
+
+### 2a. Top-level inventory
+```bash
+ls -la                          # root entries
+find . -maxdepth 2 -type d \
+  ! -path '*/node_modules/*' \
+  ! -path '*/.git/*' \
+  ! -path '*/vendor/*' \
+  ! -path '*/.next/*' \
+  ! -path '*/dist/*' \
+  ! -path '*/__pycache__/*'
+```
+
+Classify each top-level directory as one of:
+- **entry** — main executables, CLIs, servers (cmd/, bin/, app/, main.*)
+- **lib** — shared library code (lib/, pkg/, src/, internal/)
+- **ui** — frontend/views (web/, frontend/, views/, components/)
+- **config** — configuration, env templates (.env.example, config/, etc/)
+- **infra** — deployment, CI/CD, Docker (deploy/, k8s/, .github/, terraform/)
+- **test** — test-only code (test/, tests/, __tests__/, spec/)
+- **docs** — documentation (docs/, .cx/)
+- **generated** — auto-generated, do not read (dist/, build/, .next/, vendor/)
+
+### 2b. Entry points
+
+Find where execution begins:
+```bash
+# Node/Bun
+cat package.json | python3 -c "import json,sys; p=json.load(sys.stdin); print(p.get('main',''), p.get('scripts',{}))"
+
+# Go
+find . -name "main.go" ! -path '*/vendor/*'
+
+# Python
+find . -name "__main__.py" -o -name "wsgi.py" -o -name "asgi.py" | head -5
+
+# Rust
+grep -r "fn main" --include="*.rs" -l | head -5
+
+# Shell
+grep -rl "#!/" --include="*.sh" . | head -5
+```
+
+### 2c. Dependency graph (module level)
+
+```bash
+# What imports what?
+# Node — find the most imported internal modules
+grep -rh "from '\.\." --include="*.ts" --include="*.tsx" --include="*.js" . \
+  ! -path '*/node_modules/*' | sort | uniq -c | sort -rn | head -20
+
+# Go
+grep -rh '".*/' --include="*.go" . ! -path '*/vendor/*' \
+  | grep -v 'github.com/\|golang.org/' | sort | uniq -c | sort -rn | head -20
+
+# Python
+grep -rh "^from \." --include="*.py" . | sort | uniq -c | sort -rn | head -20
+```
+
+---
+
+## Phase 3: Trace the Hot Paths
+
+A "hot path" is the most important flow in the system. For most projects that's one of:
+- **Web API**: HTTP request → middleware → handler → service → DB → response
+- **CLI**: parse args → load config → execute command → output
+- **Worker**: consume queue → process → persist → emit event
+- **UI**: user action → state update → API call → render
+
+### Find the hot path:
+
+```bash
+# Largest files (usually core logic, not generated)
+find . -name "*.ts" -o -name "*.go" -o -name "*.py" -o -name "*.rs" \
+  ! -path '*/node_modules/*' ! -path '*/vendor/*' ! -path '*/dist/*' \
+  | xargs wc -l 2>/dev/null | sort -rn | head -20
+
+# Most-changed files (highest churn = highest importance)
+git log --format=format: --name-only | grep -v '^$' | sort | uniq -c | sort -rn | head -20
+
+# Most-imported files (highest fan-in = highest centrality)
+# (see Phase 2c commands above)
+```
+
+### Trace one hot path end to end:
+
+1. Pick the most central handler/service file
+2. Read it fully
+3. Follow every dependency one level deep
+4. Stop when you hit: external library call, DB query, external API call, or file I/O
+
+Document as: `ENTRY → fn1() → fn2() → fn3() → [DB|API|FS]`
+
+---
+
+## Phase 4: Identify Conventions
+
+Answer these by reading 3–5 files in each category:
+
+**Naming**: camelCase? snake_case? PascalCase for types? Consistent file naming?
+
+**Error handling**: Throw/catch? Result type? Custom error types? Error logged or propagated?
+
+**Testing**: Co-located tests (`*.test.ts`)? Separate `/test` dir? Fixtures? Mocking approach?
+
+**Dependencies**: Injected? Global singletons? Module-level init?
+
+**Configuration**: Env vars only? Config files? Validation at startup?
+
+**Auth pattern**: Middleware? Guard functions? Where are permissions enforced?
+
+```bash
+# Find test files
+find . -name "*.test.*" -o -name "*.spec.*" ! -path '*/node_modules/*' | head -20
+find . -path '*/test*' -name "*.go" | head -10
+
+# Find error types / custom errors
+grep -rl "class.*Error\|type.*Error\|errors.New\|fmt.Errorf" --include="*.ts" --include="*.go" . \
+  ! -path '*/node_modules/*' | head -10
+```
+
+---
+
+## Phase 5: Detect Debt and Gaps
+
+```bash
+# TODOs and FIXMEs (volume = debt signal)
+grep -rn "TODO\|FIXME\|HACK\|XXX\|NOSONAR" \
+  ! -path '*/node_modules/*' ! -path '*/.git/*' | wc -l
+
+grep -rn "TODO\|FIXME\|HACK" \
+  ! -path '*/node_modules/*' ! -path '*/.git/*' | head -20
+
+# Commented-out code
+grep -rn "^[[:space:]]*//.*[a-zA-Z].*[a-zA-Z]" --include="*.ts" --include="*.go" . \
+  ! -path '*/node_modules/*' | grep -v "http\|Copyright\|License" | head -20
+
+# Missing test coverage signals
+find . -name "*.ts" ! -name "*.test.ts" ! -name "*.d.ts" ! -path '*/node_modules/*' \
+  | while read f; do
+    base="${f%.ts}"
+    [ ! -f "${base}.test.ts" ] && echo "no test: $f"
+  done | head -20
+
+# Stale dependencies
+npm outdated 2>/dev/null | head -20
+go list -m -u all 2>/dev/null | grep '\[' | head -20
+```
+
+---
+
+## Phase 6: Produce the Map
+
+Write `.cx/codebase-map.md` in the project root using this template:
+
+```markdown
+# Codebase Map — {project-name}
+
+Generated: {date}
+Mapped by: cx-explorer
+
+## Overview
+{1-3 sentences: what this is, what it does, who uses it}
+
+## Tech Stack
+- Runtime: {language + version}
+- Framework: {main framework}
+- Database: {DB + ORM if any}
+- Key deps: {3-5 most important libraries}
+- Test framework: {test runner}
+
+## Structure
+| Directory | Role |
+|---|---|
+| `cmd/` | Entry points — CLI commands |
+| `internal/` | Core domain logic |
+| `pkg/` | Shared libraries |
+| ... | ... |
+
+## Entry Points
+- `{file}:{function}` — {what triggers it, e.g. "HTTP server start"}
+- `{file}:{function}` — {e.g. "CLI entrypoint"}
+
+## Hot Paths
+### {Primary flow name, e.g. "API Request → Response"}
+`handler.ts:handleRequest` → `service.ts:processRequest` → `db.ts:query` → response
+
+### {Secondary flow if applicable}
+...
+
+## Key Conventions
+- **Errors**: {how errors are handled}
+- **Config**: {how config is loaded}
+- **Auth**: {where auth is enforced}
+- **Testing**: {test file location + approach}
+- **Naming**: {naming conventions observed}
+
+## Files to Know
+| File | Why It Matters |
+|---|---|
+| `{path}` | {e.g. "Central router — all HTTP routes defined here"} |
+| `{path}` | {e.g. "DB connection pool — touch before any DB work"} |
+| `{path}` | {e.g. "Auth middleware — all protected routes pass through here"} |
+
+## Debt + Watch Areas
+- {TODO/FIXME count}: {N} open TODOs, concentrated in {area}
+- {Testing gap}: {which modules lack test coverage}
+- {Outdated deps}: {specific dep names if notable}
+- {Other}: {anything surprising or risky}
+
+## What to Read First
+If you're about to {do X}, start with: {file or path}
+If you're about to {do Y}, start with: {file or path}
+```
+
+---
+
+## Quick Reference — Useful One-Liners
+
+```bash
+# File count by extension
+find . ! -path '*/node_modules/*' ! -path '*/.git/*' -type f \
+  | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -15
+
+# Largest directories
+du -sh */ 2>/dev/null | sort -rh | head -10
+
+# Recent hot files (changed in last 30 days)
+git log --since="30 days ago" --format=format: --name-only \
+  | grep -v '^$' | sort | uniq -c | sort -rn | head -20
+
+# Who knows this codebase
+git shortlog -sn --no-merges | head -10
+
+# Find config/env loading
+grep -rn "process.env\|os.Getenv\|os.environ\|dotenv" \
+  ! -path '*/node_modules/*' -l | head -10
+
+# Find all HTTP routes
+grep -rn "router\.\|app\.get\|app\.post\|http\.HandleFunc\|@Get\|@Post" \
+  ! -path '*/node_modules/*' | head -20
+
+# Find DB schema / models
+find . -name "schema.*" -o -name "models.*" -o -name "*.prisma" \
+  -o -name "*_migration*" ! -path '*/node_modules/*' | head -10
+```
+
+---
+
+## Agent Handoffs
+
+After producing `.cx/codebase-map.md`:
+
+- **Explain architecture decisions** → `cx-architect`
+- **Trace a specific failure** → `cx-debugger` (provide the codebase-map as context)
+- **Check security posture** → `cx-security` (highlight auth files from the map)
+- **Assess test coverage** → `cx-qa` (provide the files-to-know list)
+- **Understand a library used** → `cx-docs-researcher` (provide the dep name)

package/skills/frameworks/django.md

@@ -0,0 +1,159 @@
+<!--
+skills/frameworks/django.md — Django — ```
+
+## Project Structure ```
+-->
+# Django
+
+## Project Structure
+
+```
+project/
+├── config/              ← Django settings package
+│   ├── settings/
+│   │   ├── base.py
+│   │   ├── local.py
+│   │   └── production.py
+│   ├── urls.py
+│   └── wsgi.py
+├── apps/
+│   ├── users/           ← Feature-bounded app
+│   │   ├── models.py
+│   │   ├── views.py
+│   │   ├── serializers.py
+│   │   ├── urls.py
+│   │   └── tests/
+│   └── items/
+├── manage.py
+└── requirements/
+    ├── base.txt
+    ├── local.txt
+    └── production.txt
+```
+
+Keep apps small and feature-bounded. Do not put everything in one app.
+
+## Models
+
+### Field choices
+
+- `CharField` / `TextField` — strings; always set `blank=False` unless optional
+- `UUIDField(default=uuid.uuid4, primary_key=True)` — preferred over auto-increment for external-facing IDs
+- `JSONField` — use sparingly; prefer normalized columns for queryable data
+- `select_related` for FK, `prefetch_related` for M2M — avoid N+1 queries
+
+### Migrations
+
+```bash
+python manage.py makemigrations --check    # CI gate — fail if migrations needed
+python manage.py migrate --plan            # Preview before applying
+```
+
+- Never edit applied migrations; create new ones
+- For large tables, use `RunSQL` with `CONCURRENTLY` for index additions in production
+- Zero-downtime: add nullable column → deploy → backfill → add constraint → deploy
+
+### Model managers
+
+Encapsulate query logic in managers, not views:
+
+```python
+class PublishedManager(models.Manager):
+  def get_queryset(self):
+    return super().get_queryset().filter(status='published')
+
+class Item(models.Model):
+  objects = models.Manager()
+  published = PublishedManager()
+```
+
+## Views
+
+### Prefer Class-Based Views (CBV) for standard CRUD
+
+```python
+class ItemDetailView(LoginRequiredMixin, DetailView):
+  model = Item
+  template_name = 'items/detail.html'
+  context_object_name = 'item'
+```
+
+Use function-based views for one-off logic that doesn't fit CBV patterns.
+
+### Django REST Framework (DRF)
+
+```python
+class ItemViewSet(viewsets.ModelViewSet):
+  queryset = Item.objects.select_related('owner')
+  serializer_class = ItemSerializer
+  permission_classes = [IsAuthenticated]
+  filterset_fields = ['status']
+```
+
+Routers auto-wire CRUD endpoints:
+
+```python
+router = DefaultRouter()
+router.register('items', ItemViewSet)
+urlpatterns = [path('api/', include(router.urls))]
+```
+
+### Serializer validation
+
+```python
+class ItemSerializer(serializers.ModelSerializer):
+  class Meta:
+    model = Item
+    fields = ['id', 'title', 'status']
+    read_only_fields = ['id']
+
+  def validate_title(self, value):
+    if len(value) < 3:
+      raise serializers.ValidationError('Title too short.')
+    return value
+```
+
+## Security
+
+- `SECRET_KEY` from env — never commit
+- `ALLOWED_HOSTS` locked down in production
+- `DEBUG = False` in production (template errors expose internals)
+- CSRF: enabled by default for form views; DRF uses `SessionAuthentication` + CSRF for browser clients
+- `django-environ` or `python-decouple` for settings from environment variables
+- Content security policy: `django-csp` middleware
+- SQL: always use ORM or parameterized `raw()` — never string-format user input into queries
+
+## Testing
+
+```python
+class ItemAPITest(APITestCase):
+  def setUp(self):
+    self.user = User.objects.create_user(username='tester', password='pass')
+    self.client.force_authenticate(self.user)
+
+  def test_create_item(self):
+    resp = self.client.post('/api/items/', {'title': 'New Item'})
+    self.assertEqual(resp.status_code, 201)
+    self.assertEqual(Item.objects.count(), 1)
+```
+
+- Use `APITestCase` (DRF) for API tests — wraps each test in a transaction that rolls back
+- `factory_boy` for fixtures — more maintainable than raw `create()`
+- `pytest-django` with `@pytest.mark.django_db` for pytest-style tests
+- `django-silk` or `django-debug-toolbar` for query profiling in development
+
+## Performance
+
+- Database: add `db_index=True` for filtered columns; `select_related`/`prefetch_related` to eliminate N+1
+- Caching: `django.core.cache` with Redis backend (`django-redis`)
+- Async views: `async def` views supported in Django 4.1+ — use for I/O-bound operations with `asyncio`
+- Task queues: `Celery` + Redis/RabbitMQ for background jobs; `django-celery-beat` for scheduling
+- `gunicorn` + `uvicorn` workers for async support in production
+
+## Common Pitfalls
+
+- `objects.all()` in views without pagination — always use `Paginator` or DRF `pagination_class`
+- Accessing related objects in a loop without `select_related` — profile with `django-debug-toolbar`
+- `settings.DEBUG` checks in production-like environments — use environment-specific settings modules
+- File uploads to local storage in production — use `django-storages` with S3/GCS
+- Signals for business logic — prefer explicit service functions; signals are invisible and hard to test

package/skills/frameworks/nextjs.md

@@ -0,0 +1,148 @@
+<!--
+skills/frameworks/nextjs.md — Next.js (App Router) — ```
+
+## App Router Mental Model ```
+-->
+# Next.js (App Router)
+
+## App Router Mental Model
+
+```
+app/
+├── layout.tsx          ← Root layout — wraps every page
+├── page.tsx            ← / route
+├── (auth)/             ← Route group (no URL segment)
+│   ├── login/page.tsx  ← /login
+│   └── register/page.tsx
+├── dashboard/
+│   ├── layout.tsx      ← Nested layout for /dashboard/*
+│   └── page.tsx        ← /dashboard
+└── api/
+    └── items/route.ts  ← /api/items (Route Handler)
+```
+
+Key rules:
+- `page.tsx` = publicly accessible route segment
+- `layout.tsx` = persistent shell across sibling pages
+- `loading.tsx` = automatic Suspense boundary while segment loads
+- `error.tsx` = error boundary for the segment
+- `not-found.tsx` = 404 for the segment
+
+## Data Fetching
+
+### Server Components fetch directly
+
+```tsx
+// app/items/page.tsx
+async function ItemsPage() {
+  const items = await fetch('https://api.example.com/items', {
+    next: { revalidate: 60 }   // ISR: revalidate every 60s
+  }).then(r => r.json());
+  return <ItemList items={items} />;
+}
+```
+
+Caching behaviors:
+
+| Option | Behavior |
+|---|---|
+| `cache: 'force-cache'` | Static — cache forever (default) |
+| `next: { revalidate: N }` | ISR — revalidate after N seconds |
+| `cache: 'no-store'` | Dynamic — always fresh |
+| `next: { tags: ['items'] }` | Tag for on-demand revalidation |
+
+### On-demand revalidation
+
+```ts
+// Server Action or API Route
+import { revalidateTag } from 'next/cache';
+revalidateTag('items');   // invalidates all fetches tagged 'items'
+```
+
+### Route Handlers (API Routes replacement)
+
+```ts
+// app/api/items/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function GET(req: NextRequest) {
+  const items = await db.items.findMany();
+  return NextResponse.json(items);
+}
+```
+
+## Server Actions
+
+Mutate data from Client Components without a separate API route:
+
+```tsx
+// app/actions.ts
+'use server';
+export async function createItem(formData: FormData) {
+  const title = formData.get('title') as string;
+  await db.items.create({ data: { title } });
+  revalidatePath('/items');
+}
+
+// Client Component
+<form action={createItem}>
+  <input name="title" />
+  <button>Create</button>
+</form>
+```
+
+Validate Server Action inputs — they are network endpoints.
+
+## Rendering Strategies
+
+| Strategy | When |
+|---|---|
+| Static (SSG) | Marketing pages, docs — no user-specific data |
+| ISR | Listings, product pages — stale-ok, periodic refresh |
+| Dynamic (SSR) | Dashboards, auth-gated pages — always fresh |
+| Client | Highly interactive UIs, real-time, after-hydration only |
+
+Prefer static/ISR by default; reach for dynamic only when the data must be per-request.
+
+## Metadata & SEO
+
+```tsx
+// Static
+export const metadata: Metadata = { title: 'Items', description: '...' };
+
+// Dynamic
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const item = await fetchItem(params.id);
+  return { title: item.title };
+}
+```
+
+## Middleware
+
+```ts
+// middleware.ts (runs at the edge before the request)
+export function middleware(req: NextRequest) {
+  if (!req.cookies.get('session')) {
+    return NextResponse.redirect(new URL('/login', req.url));
+  }
+}
+export const config = { matcher: ['/dashboard/:path*'] };
+```
+
+Middleware runs on the Edge Runtime — no Node.js APIs. Keep it fast; no DB calls.
+
+## Performance
+
+- Enable Partial Prerendering (PPR) in Next.js 15 for shell + streaming content
+- Use `next/image` for all images — automatic WebP, lazy loading, CLS prevention
+- Use `next/font` for self-hosted fonts — eliminates FOUT and external requests
+- Bundle analysis: `ANALYZE=true next build`
+- Streaming: wrap slow data-dependent sections in `<Suspense>`
+
+## Common Pitfalls
+
+- Importing client-only code (browser APIs, hooks) in Server Components — add `'use client'`
+- Large `layout.tsx` re-renders — use `memo` on stable child subtrees
+- Fetching the same data in multiple components — hoist to the nearest shared ancestor Server Component (fetch is deduplicated within a request)
+- Dynamic routes missing `generateStaticParams` for static builds — causes runtime 404
+- Server Actions called without input validation — treat as untrusted user input