feat: add 6 tooling skills to .agents/skills/

.agents/skills/constructive-cli/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: constructive-cli
+description: "Generated CLI commands and scaffolding — how the CLI is generated from GraphQL schemas, how to use it, codegen options, multi-target unified CLI, and the CLI reference. Use when asked to 'generate a CLI', 'create CLI commands', 'build a command-line client', 'run generated CLI', or when working with @constructive-io/graphql-codegen CLI output."
+metadata:
+  author: constructive-io
+  version: "1.0.0"
+---
+
+# Constructive CLI (Generated)
+
+The Constructive codegen pipeline generates interactive command-line interfaces from GraphQL schemas using inquirerer. The generated CLI provides CRUD commands for each table and custom operations, plus built-in infrastructure commands for authentication and context management.
+
+## When to Apply
+
+Use this skill when:
+- Generating a CLI tool from a GraphQL schema
+- Running or customizing the generated CLI
+- Understanding the CLI codegen pipeline
+- Building internal tooling or admin scripts from GraphQL APIs
+- Configuring multi-target unified CLI output
+
+## How the CLI Is Generated
+
+The CLI is generated by `@constructive-io/graphql-codegen` alongside the ORM client:
+
+```typescript
+import { generate } from '@constructive-io/graphql-codegen';
+
+await generate({
+  schemaFile: './schemas/public.graphql',
+  output: './generated',
+  cli: true,  // ORM is auto-generated alongside CLI
+});
+```
+
+### CLI Configuration Options
+
+```typescript
+cli: {
+  toolName: 'myapp',       // Config stored at ~/.myapp/ via appstash
+  entryPoint: true,         // Generate runnable index.ts
+  builtinNames: {
+    auth: 'credentials',   // Rename infrastructure commands
+    context: 'env',
+  },
+}
+```
+
+## Output Structure
+
+```
+{output}/cli/
+├── index.ts              # Entry point (only if entryPoint: true)
+├── executor.ts           # CLI executor with command routing
+├── command-map.ts        # Map of all commands
+├── context.ts            # Infrastructure: context management
+├── auth.ts               # Infrastructure: auth/credentials
+├── utils.ts              # Shared CLI utilities
+└── commands/
+    ├── users.ts           # Generated CRUD commands per table
+    └── ...
+```
+
+## Running the Generated CLI
+
+```bash
+# With entry point
+npx ts-node generated/cli/index.ts
+
+# Or compile and run
+npx tsc && node dist/generated/cli/index.js
+```
+
+## Built-in Infrastructure Commands
+
+### context — Manage API endpoints
+
+```bash
+myapp context create production --endpoint https://api.example.com/graphql
+myapp context list
+myapp context use production
+myapp context current
+```
+
+### auth — Manage API credentials
+
+```bash
+myapp auth set-token <your-bearer-token>
+myapp auth status
+myapp auth logout
+```
+
+### Builtin Name Collision Handling
+
+If a table name collides with `auth` or `context`, the infrastructure command is automatically renamed (`auth` → `credentials`, `context` → `env`). Override with `builtinNames`.
+
+## Multi-Target CLI (Unified)
+
+Combine all targets into a single CLI with namespaced commands:
+
+```typescript
+import { generateMulti } from '@constructive-io/graphql-codegen';
+
+await generateMulti({
+  configs: {
+    public: { schemaFile: './schemas/public.graphql', output: './generated/public', cli: true },
+    admin: { schemaFile: './schemas/admin.graphql', output: './generated/admin', cli: true },
+  },
+  unifiedCli: { toolName: 'myapp', entryPoint: true },
+});
+// Commands: myapp public users list, myapp admin users list
+```
+
+## Reference Guide
+
+| Reference | Topic | Consult When |
+|-----------|-------|--------------|
+| [references/codegen-cli-reference.md](references/codegen-cli-reference.md) | Full CLI codegen reference | Looking up CLI flags, source options, environment variables |
+
+## Cross-References
+
+- `constructive-sdk-graphql` skill (in constructive-skills) — Full codegen pipeline (hooks, ORM, CLI generation)
+- `pgpm` skill — Database migrations (deploy before generating CLI)
+- `constructive-setup` skill — Monorepo setup and local development

.agents/skills/constructive-cli/references/codegen-cli-reference.md

@@ -0,0 +1,111 @@
+# CLI Codegen Reference
+
+Complete reference for `@constructive-io/graphql-codegen` CLI commands.
+
+## @constructive-io/graphql-codegen generate
+
+Generate type-safe React Query hooks and/or ORM client from GraphQL schema.
+
+```bash
+npx @constructive-io/graphql-codegen generate [options]
+```
+
+### Source Options (choose one)
+
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--endpoint <url>` | `-e` | GraphQL endpoint URL | - |
+| `--schema-file <path>` | `-s` | Path to GraphQL schema file (.graphql) | - |
+| `--schemas <list>` | - | PostgreSQL schemas (comma-separated) | - |
+| `--api-names <list>` | - | API names for auto schema discovery | - |
+| `--config <path>` | `-c` | Path to config file | `graphql-codegen.config.ts` |
+
+### Generator Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--react-query` | Generate React Query hooks | `false` |
+| `--orm` | Generate ORM client | `false` |
+
+### Output Options
+
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--output <dir>` | `-o` | Output directory | `./generated/graphql` |
+| `--target <name>` | `-t` | Target name (for multi-target configs) | - |
+
+### Schema Export Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--schema-enabled` | Export GraphQL SDL schema file | `false` |
+| `--schema-output <dir>` | Output directory for exported schema | Same as `--output` |
+| `--schema-filename <name>` | Filename for exported schema | `schema.graphql` |
+
+### Other Options
+
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--authorization <token>` | `-a` | Authorization header value | - |
+| `--verbose` | `-v` | Show detailed output | `false` |
+| `--dry-run` | - | Preview without writing files | `false` |
+
+## Examples
+
+### From GraphQL Endpoint
+
+```bash
+npx @constructive-io/graphql-codegen generate --react-query --endpoint https://api.example.com/graphql
+npx @constructive-io/graphql-codegen generate --orm --endpoint https://api.example.com/graphql
+npx @constructive-io/graphql-codegen generate --react-query --orm --endpoint https://api.example.com/graphql
+```
+
+### From Schema File
+
+```bash
+npx @constructive-io/graphql-codegen generate --react-query --schema-file ./schema.graphql
+```
+
+### From Database
+
+```bash
+npx @constructive-io/graphql-codegen generate --react-query --schemas public,app_public
+npx @constructive-io/graphql-codegen generate --orm --api-names my_api
+```
+
+### Using Config File
+
+```bash
+npx @constructive-io/graphql-codegen generate
+npx @constructive-io/graphql-codegen generate --config ./config/codegen.config.ts
+npx @constructive-io/graphql-codegen generate --target production  # Multi-target
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PGHOST` | PostgreSQL host (for database introspection) |
+| `PGPORT` | PostgreSQL port |
+| `PGDATABASE` | PostgreSQL database name |
+| `PGUSER` | PostgreSQL user |
+| `PGPASSWORD` | PostgreSQL password |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | General error |
+| `2` | Configuration error |
+| `3` | Network/schema error |
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| No code generated | Add `--react-query` or `--orm` flag |
+| "Cannot use both endpoint and schemas" | Choose one schema source |
+| No CLI generated | Add `cli: true` to generate options |
+| Auth errors | Run `{toolName} auth set-token <token>` |
+| Wrong endpoint | Run `{toolName} context use <name>` |

.agents/skills/constructive-pnpm/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: constructive-pnpm
+description: "PNPM workspace management — monorepo configuration, dist-folder publishing with makage/lerna, dependency management, deep nested imports, and anti-patterns to avoid. Use when configuring pnpm workspaces, publishing packages to npm, managing monorepo dependencies, or setting up new TypeScript packages."
+metadata:
+  author: constructive-io
+  version: "1.0.0"
+---
+
+# Constructive PNPM
+
+PNPM workspace management, package publishing, and monorepo best practices for Constructive projects.
+
+## When to Apply
+
+Use this skill when:
+- Configuring pnpm workspaces and monorepo settings
+- Publishing TypeScript packages to npm with makage and lerna
+- Managing workspace dependencies and cross-package references
+- Setting up the dist-folder publishing pattern
+- Understanding deep nested imports vs `exports` map (anti-pattern)
+
+## Key Concepts
+
+### Dist-Folder Publishing (TypeScript/JS Only)
+
+Constructive publishes **TypeScript/JS packages** from the `dist/` folder, which becomes the package root on npm. This means:
+- `main: "index.js"` points to `dist/index.js` after publish
+- Consumers never see `dist/` in their import paths
+- No `exports` field needed — standard Node.js resolution works
+- Uses `makage build` to compile TypeScript and copy assets to `dist/`
+- `publishConfig.directory: "dist"` in package.json
+
+**This does NOT apply to pgpm SQL modules.** PGPM modules publish from the package root (no `dist/` folder, no makage). They use `pgpm package` to bundle SQL files instead. See the `pgpm` skill ([publishing.md](../pgpm/references/publishing.md)) for the SQL module publishing workflow.
+
+### Deep Nested Imports (NOT `exports` Map)
+
+**NEVER use the `exports` map pattern.** Instead, use deep nested imports via file paths:
+
+```typescript
+// Correct: deep nested import (works because dist/ becomes package root)
+import { OrmClient } from '@my-org/sdk/api';
+import { generateOrm } from '@constructive-io/graphql-codegen/core/codegen/orm';
+
+// WRONG: exports map anti-pattern
+// "exports": { "./api": { "import": "./dist/api/index.js" } }
+```
+
+See [pnpm-publishing.md](./references/pnpm-publishing.md) for the full explanation.
+
+## Reference Guide
+
+| Reference | Topic | Consult When |
+|-----------|-------|--------------|
+| [pnpm-workspace.md](./references/pnpm-workspace.md) | pnpm workspace overview | Setting up monorepo, workspace configuration |
+| [pnpm-monorepo-management.md](./references/pnpm-monorepo-management.md) | Monorepo management | Cross-package dependencies, filtering, CI/CD patterns |
+| [pnpm-publishing.md](./references/pnpm-publishing.md) | Publishing packages | Lerna versioning, makage builds, dist-folder pattern |
+
+## Cross-References
+
+- `inquirerer-cli` — CLI building with inquirerer, README formatting
+- `pgpm` — PGPM workspaces for SQL modules (different from pnpm workspaces)
+- `constructive-platform` — Platform core, environment configuration