@xonovex/skills 0.1.0

package/skills/hono-opinionated-guidelines/reference/openapi-router-hierarchy.md

@@ -0,0 +1,64 @@
+# openapi-router-hierarchy: Use OpenAPIHono Throughout Router Hierarchy
+
+**Guideline:** Use `OpenAPIHono` for all routers in the hierarchy (root, intermediate, and leaf) to ensure OpenAPI routes appear in the generated specification.
+
+**Rationale:** OpenAPI metadata propagation works through the router chain only when all routers use `OpenAPIHono`. Mixing regular `Hono` with `OpenAPIHono` breaks metadata propagation, causing child OpenAPI routes to be "lost" and resulting in incomplete API documentation.
+
+**Example:**
+
+```typescript
+// src/app.ts - Root router
+// src/routes/v1/index.ts - Intermediate router
+
+// src/routes/v1/items.ts - Leaf router
+import {
+  createRoute,
+  OpenAPIHono,
+  OpenAPIHono,
+  OpenAPIHono,
+  z,
+} from "@hono/zod-openapi";
+
+export function createApp() {
+  // ✅ Use OpenAPIHono for root
+  const app = new OpenAPIHono();
+
+  app.use("*", logger());
+  app.route("/api/v1", v1Router);
+
+  return app;
+}
+
+// ✅ Use OpenAPIHono for intermediate router
+export const v1Router = new OpenAPIHono();
+
+v1Router.route("/items", itemsRouter);
+v1Router.route("/users", usersRouter);
+
+// ✅ Use OpenAPIHono for leaf router
+export const itemsRouter = new OpenAPIHono();
+
+const listItemsRoute = createRoute({
+  method: "get",
+  path: "/",
+  responses: {
+    200: {
+      content: {"application/json": {schema: ItemListSchema}},
+      description: "List of items",
+    },
+  },
+});
+
+itemsRouter.openapi(listItemsRoute, (c) => {
+  // Handler implementation
+});
+```
+
+**Techniques:**
+- Import `OpenAPIHono` from `@hono/zod-openapi`
+- Use `OpenAPIHono` for root application router
+- Use `OpenAPIHono` for all intermediate routers (version routers, feature groupings)
+- Use `OpenAPIHono` for all leaf routers (domain-specific routes)
+- Mount routers normally with `.route()` method
+- Verify all routes appear in generated `/openapi.json` spec
+- Regular non-OpenAPI routes can coexist on OpenAPIHono routers

package/skills/hono-opinionated-guidelines/reference/openapi-spec-generation.md

@@ -0,0 +1,57 @@
+# openapi-spec-generation: Use app.doc() for Automatic OpenAPI Spec Generation
+
+**Guideline:** Use the `app.doc()` method to automatically generate OpenAPI specifications from registered routes instead of maintaining static documents.
+
+**Rationale:** Manual OpenAPI documents drift out of sync with implementation, require constant maintenance, and create a duplicate source of truth. The `app.doc()` method automatically extracts route metadata from route definitions, building complete documentation that stays synchronized with the actual implementation.
+
+**Example:**
+
+```typescript
+import {createRoute, OpenAPIHono, z} from "@hono/zod-openapi";
+
+const app = new OpenAPIHono();
+
+// Define and register OpenAPI routes
+const listItemsRoute = createRoute({
+  method: "get",
+  path: "/items",
+  responses: {
+    200: {
+      content: {"application/json": {schema: ItemListSchema}},
+      description: "List of items",
+    },
+  },
+});
+
+app.openapi(listItemsRoute, (c) => {
+  // Handler implementation
+});
+
+// ✅ CORRECT - Auto-generate spec with app.doc()
+app.doc("/openapi.json", {
+  openapi: "3.1.0",
+  info: {
+    title: "Hono Backend API",
+    version: "1.0.0",
+    description: "API for managing items and uploads",
+  },
+  servers: [
+    {
+      url: "http://localhost:3000",
+      description: "Development",
+    },
+  ],
+});
+
+// Access spec at: http://localhost:3000/openapi.json
+// Spec automatically includes all registered OpenAPI routes
+```
+
+**Techniques:**
+- Ensure your app uses `OpenAPIHono` (not regular `Hono`)
+- Define routes using `createRoute()` with full request and response schemas
+- Register routes using `router.openapi(route, handler)` method
+- Call `app.doc(path, metadata)` to register spec endpoint
+- Provide OpenAPI metadata: openapi version, info object, servers
+- Access the spec at the registered path (e.g., `/openapi.json`)
+- Never manually create or maintain the `paths` object

package/skills/hono-opinionated-guidelines/reference/platform-runtime.md

@@ -0,0 +1,41 @@
+# platform-runtime: Platform-Specific Runtime Detection
+
+**Guideline:** Use `env()` for unified environment variables and `getRuntimeKey()` for platform-specific code paths.
+
+**Rationale:** Hono runs on different runtimes with different APIs and behaviors. Unified helpers enable portable code across all platforms.
+
+**Example:**
+
+```typescript
+import {Hono} from "hono";
+import {env, getRuntimeKey} from "hono/adapter";
+import {getConnInfo} from "hono/cloudflare-workers";
+
+const app = new Hono();
+
+// Unified environment access
+app.get("/config", (c) => {
+  const {DATABASE_URL} = env<{DATABASE_URL: string}>(c);
+  return c.json({configured: !!DATABASE_URL});
+});
+
+// Platform-specific logic
+app.use("*", async (c, next) => {
+  const runtime = getRuntimeKey();
+  c.header("X-Runtime", runtime === "workerd" ? "cloudflare" : runtime);
+  await next();
+});
+
+// Connection info
+app.get("/ip", (c) => {
+  const info = getConnInfo(c);
+  return c.json({ip: info.remote.address});
+});
+```
+
+**Techniques:**
+- Import `env` and `getRuntimeKey` from `hono/adapter`
+- Use `env(c)` instead of `process.env` or `Deno.env`
+- Check runtime with `getRuntimeKey()` for platform-specific logic
+- Import connection info from platform-specific paths
+- Handle platform differences (Deno cache requires `wait: true`, Node.js needs compression middleware)

package/skills/hono-opinionated-guidelines/reference/router-selection.md

@@ -0,0 +1,34 @@
+# router-selection: Choosing the Right Router for Your Environment
+
+**Guideline:** Select the appropriate Hono router based on deployment environment, optimizing for cold start times in serverless/edge or throughput in traditional servers.
+
+**Rationale:** Hono provides multiple router implementations: RegExpRouter (fastest throughput via single regex), LinearRouter (optimized for serverless cold starts), SmartRouter (default, supports all patterns), and PatternRouter (smallest footprint). Choosing correctly impacts cold starts, request throughput, and memory usage.
+
+**Example:**
+
+```typescript
+import {Hono} from "hono";
+import {LinearRouter} from "hono/router/linear-router";
+import {RegExpRouter} from "hono/router/reg-exp-router";
+
+// High-throughput traditional server
+const app = new Hono({
+  router: new RegExpRouter(),
+});
+
+// Serverless/edge with fast initialization
+const serverlessApp = new Hono({
+  router: new LinearRouter(),
+});
+
+// Default SmartRouter (no configuration needed)
+const defaultApp = new Hono();
+```
+
+**Techniques:**
+- Identify deployment environment: serverless/edge (prioritize cold starts) or traditional server
+- Use LinearRouter for serverless/edge environments with repeated initialization
+- Use RegExpRouter for high-throughput APIs with persistent connections
+- Use SmartRouter (default) when unsure or mixing pattern types
+- Consider route complexity: wildcards, optional params, regex patterns
+- Profile cold start times and request throughput for your specific use case

package/skills/hono-opinionated-guidelines/reference/security-middleware.md

@@ -0,0 +1,60 @@
+# security-middleware: Built-in Security Middleware Configuration
+
+**Guideline:** Use Hono's built-in security middleware for authentication, CSRF protection, and security headers, applying `secureHeaders()` first in the middleware chain.
+
+**Rationale:** Hono provides battle-tested security middleware implementations for basic auth, bearer tokens, JWT verification, CSRF protection, and IP restriction with consistent configuration patterns and type safety, eliminating the need for external dependencies.
+
+**Example:**
+
+```typescript
+import {Hono} from "hono";
+import {basicAuth} from "hono/basic-auth";
+import {bearerAuth} from "hono/bearer-auth";
+import {csrf} from "hono/csrf";
+import {ipRestriction} from "hono/ip-restriction";
+import {secureHeaders} from "hono/secure-headers";
+
+const app = new Hono();
+
+// Apply secure headers first
+app.use("*", secureHeaders());
+
+// CSRF protection for form submissions
+app.use("/forms/*", csrf());
+
+// Bearer auth with custom verification
+app.use(
+  "/api/*",
+  bearerAuth({
+    verifyToken: async (token, c) => {
+      return await tokenService.verify(token);
+    },
+  }),
+);
+
+// Basic auth for admin routes
+app.use(
+  "/admin/*",
+  basicAuth({
+    verifyUser: (username, password, c) => {
+      return username === "admin" && password === process.env.ADMIN_PASSWORD;
+    },
+  }),
+);
+
+// IP restriction for internal routes
+app.use(
+  "/internal/*",
+  ipRestriction({
+    denyList: [],
+    allowList: ["192.168.0.0/16", "10.0.0.0/8"],
+  }),
+);
+```
+
+**Techniques:**
+- Import middleware from `hono/` subpaths (basicAuth, bearerAuth, csrf, secureHeaders, ipRestriction)
+- Apply security headers first in middleware chain to protect all routes
+- Use custom verifiers for dynamic authentication logic
+- Configure CSRF protection for form-based applications
+- Restrict IPs for admin and internal routes using CIDR notation

package/skills/hono-opinionated-guidelines/reference/validation-type-safety.md

@@ -0,0 +1,43 @@
+# validation-type-safety: Request Validation and Type Safety with Zod
+
+**Guideline:** Cast `c.req.valid` to specify return types and cast validation errors to `z.ZodError` to restore type safety when using Hono's base Context type.
+
+**Rationale:** Hono's Context type without generic validation types returns `any` from `c.req.valid()`, losing type safety. Type assertions restore compile-time type checking without complex nested generics, enabling autocomplete and error detection while keeping signatures simple.
+
+**Example:**
+
+```typescript
+import {zValidator} from "@hono/zod-validator";
+import type {Context} from "hono";
+import type {z} from "zod";
+import {CreateUserSchema, type CreateUser} from "../schemas/users.js";
+
+// Controller with type-safe validation
+export function createUser(c: Context) {
+  // Cast c.req.valid to specify return type
+  const data = (c.req.valid as (target: string) => CreateUser)("json");
+
+  // Now `data` has full type information
+  const user = userService.create(data);
+  return c.json(user, 201);
+}
+
+usersRouter.post(
+  "/",
+  zValidator("json", CreateUserSchema, (result, c) => {
+    if (!result.success) {
+      // Cast to z.ZodError for type-safe error processing
+      return badRequest(c, result.error as z.ZodError);
+    }
+  }),
+  controller.createUser,
+);
+```
+
+**Techniques:**
+- Define Zod schemas for request payloads with TypeScript type exports
+- In controllers using base `Context`, cast `c.req.valid` with target parameter
+- Specify the return type in the cast (e.g., `CreateUser`)
+- In zValidator error handlers, cast `result.error` to `z.ZodError`
+- Use typed validation errors in error response functions
+- Apply same pattern to query params and path params

package/skills/hono-opinionated-guidelines/reference/websocket-support.md

@@ -0,0 +1,59 @@
+# websocket-support: WebSocket Server Setup and Route Patterns
+
+**Guideline:** Keep the object reference returned from `createNodeWebSocket()` and call methods on that object rather than destructuring, to maintain proper `this` binding.
+
+**Rationale:** JavaScript methods that rely on `this` context lose their binding when destructured. The `@hono/node-ws` package's `createNodeWebSocket()` returns methods that depend on `this` to access internal state. Keeping the object reference preserves the binding while factory functions like `upgradeWebSocket` can safely be destructured.
+
+**Example:**
+
+```typescript
+import {serve} from "@hono/node-server";
+import {createNodeWebSocket} from "@hono/node-ws";
+import {Hono} from "hono";
+import {createApp} from "./app.js";
+
+const app = createApp();
+
+// ✅ CORRECT - Keep object reference
+const wsHelpers = createNodeWebSocket({app});
+
+const server = serve({
+  fetch: app.fetch,
+  port: 3000,
+});
+
+// Call method on object to maintain binding
+wsHelpers.injectWebSocket(server);
+
+// Destructuring upgradeWebSocket is safe (it's a factory)
+const {upgradeWebSocket} = createNodeWebSocket({app: new Hono()});
+
+export const wsRouter = new Hono();
+
+wsRouter.get(
+  "/chat",
+  upgradeWebSocket(() => ({
+    onOpen(_evt, ws) {
+      console.log("Client connected");
+    },
+    onMessage(event, ws) {
+      const data = JSON.parse(String(event.data)) as {message: string};
+      ws.send(JSON.stringify({echo: data.message}));
+    },
+    onClose(_evt, ws) {
+      console.log("Client disconnected");
+    },
+    onError(evt, ws) {
+      console.error("WebSocket error:", evt);
+    },
+  })),
+);
+```
+
+**Techniques:**
+- Import `createNodeWebSocket` from `@hono/node-ws` and call with `{app}` parameter
+- Keep entire object reference (e.g., `wsHelpers`) for method-based APIs
+- Call methods on the object: `wsHelpers.injectWebSocket(server)`
+- Destructuring factory functions like `upgradeWebSocket` is safe
+- Define WebSocket handlers with onOpen, onMessage, onClose, onError callbacks
+- Use TypeScript types for message data to ensure type safety

package/skills/insights-guidelines/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: insights-guidelines
+description: >-
+  Trigger on post-session reflection and skill improvement tasks. Use when analyzing development sessions for lessons learned. Apply for extracting insights, integrating into skills. Keywords: mistakes, discoveries, patterns, insights extraction, skill integration, lessons learned, development session analysis.
+---
+
+# Insights Guidelines
+
+## Core Principles
+
+- **Extract from Experience** - Analyze session for development errors and corrections, see [reference/insights-extract.md](reference/insights-extract.md)
+- **Identify Patterns** - Find general patterns beyond current task
+- **Document Structure** - Save with frontmatter for tracking and integration
+- **Progressive Integration** - Convert insights into skill guidelines, see [reference/insights-integrate.md](reference/insights-integrate.md)
+
+## Workflow
+
+- **Extract** - Review conversation, document category/topic/mistake/discovery/fix, see [reference/insights-extract.md](reference/insights-extract.md)
+- **Save** - Create separate files with frontmatter for each insight
+- **Integrate** - Convert to progressive disclosure skills, mark as applied, see [reference/insights-integrate.md](reference/insights-integrate.md)
+
+## Progressive Disclosure
+
+### Insight Extraction
+- Read [reference/insights-extract.md](reference/insights-extract.md) - Analyze session for development lessons
+
+### Insight Integration
+- Read [reference/insights-integrate.md](reference/insights-integrate.md) - Convert insights to progressive disclosure skills

package/skills/insights-guidelines/reference/insights-extract.md

@@ -0,0 +1,31 @@
+# insights-extract: Extract Development Lessons
+
+**Guideline:** Extract development mistakes and lessons learned from sessions into structured insight files with frontmatter metadata.
+
+**Rationale:** Captures learning from errors during development. Structured insights with frontmatter can be tracked and later integrated into permanent guidelines to improve team practices.
+
+**Example:**
+
+```markdown
+---
+category: testing
+topic: json-response-type-safety
+applies_to: [API testing, Hono testing]
+created: "2025-01-07"
+applied: false
+---
+
+# Testing: JSON Response Type Safety
+
+- **MISTAKE**: Expected JSON response parsing to provide type safety automatically
+- **DISCOVERY**: Tests passed but runtime errors occurred with incorrect property access
+- **FIX**: Use Zod schema validation on response.json() results
+- **APPLIES TO**: API testing, Response validation
+```
+
+**Techniques:**
+- Review session for development errors and corrections made
+- Extract patterns applicable beyond current task
+- Create insight file with frontmatter: category, topic, applies_to, created, applied
+- Document: MISTAKE, DISCOVERY, FIX, APPLIES TO sections
+- Categorize by technology and domain for later discovery

package/skills/insights-guidelines/reference/insights-integrate.md

@@ -0,0 +1,35 @@
+# insights-integrate: Convert Insights to Skills
+
+**Guideline:** Integrate extracted insights into Claude skills with progressive disclosure structure, creating or merging into category-specific guidelines.
+
+**Rationale:** Transforms session insights into permanent, discoverable guidelines organized by topic in detail files, enabling knowledge reuse without cluttering main skill documentation.
+
+**Example:**
+
+```markdown
+---
+name: testing-guidelines
+description: Use when writing tests. Apply for type safety, mocking, async patterns.
+---
+
+## Essentials
+
+- Validate all external inputs
+- Type-check response data with Zod schemas
+- Mock external dependencies deterministically
+- Test error paths explicitly
+- Use test factories for complex data
+
+## Progressive Disclosure
+
+- Read [details/json-response-validation.md](details/json-response-validation.md) - When validating API responses
+```
+
+**Techniques:**
+- Search insights/ directory for category-matching insight files
+- Parse content and extract topics with MISTAKE/DISCOVERY/FIX sections
+- Generate or merge SKILL.md: Essentials (3-7 items), Progressive Disclosure links
+- Create detail files from each insight using standard Guideline/Rationale/Example/Techniques format
+- Deduplicate essentials keeping most important items
+- Preserve existing detail files when merging
+- Mark integrated insights as `applied: true`

package/skills/instruction-guidelines/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: instruction-guidelines
+description: >-
+  Trigger on `AGENTS.md`, `CLAUDE.md` files. Use when working with project instruction files. Apply for assimilating patterns, simplifying verbosity, syncing directory structure. Keywords: AGENTS.md, CLAUDE.md, project instructions, directory structure, patterns, dry-run, preserve context.
+---
+
+# Project Instruction Guidelines
+
+## Core Principles
+
+- **Preserve Project Context** - Never modify technology names, paths, or commands
+- **Match Style and Voice** - Maintain target file's formatting and terminology
+- **Structure Integrity** - Keep section order and hierarchy intact
+- **Safe Modifications** - Use dry-run to preview changes before applying
+
+## Common Operations
+
+- **Assimilate** - Extract organizational patterns from source and integrate into target
+- **Simplify** - Reduce verbosity while preserving structure and workflows
+- **Sync** - Update directory listings to reflect current filesystem state
+
+## Progressive Disclosure
+
+- **Assimilate patterns** - Augment instructions with patterns from another file, see [reference/assimilate.md](reference/assimilate.md)
+- **Simplify instructions** - Reduce verbosity in AGENTS.md/CLAUDE.md, see [reference/simplify.md](reference/simplify.md)
+- **Sync with filesystem** - Update directory structure to current state, see [reference/sync.md](reference/sync.md)

package/skills/instruction-guidelines/reference/assimilate.md

@@ -0,0 +1,38 @@
+# assimilate: Extract Patterns from Source Instructions
+
+**Guideline:** Extract organizational patterns from source AGENTS.md/CLAUDE.md and integrate into target while preserving structure, style, technology names, and context.
+
+**Rationale:** Share organizational patterns between projects without losing project-specific details, technology choices, or critical context that defines how the project operates.
+
+**Example:**
+
+```bash
+# Source: source-project AGENTS.md
+# Target: target-project AGENTS.md
+
+# Extract workflow pattern from source:
+# "Setup: npm install, git lfs pull"
+# "Tasks: npx moon run <project>:<task>"
+
+# Apply to target with its technology names:
+# Target uses Gradle and Maven instead of npm
+# Result: "Setup: gradle build, git lfs pull"
+#         "Tasks: gradle run <project>:<task>"
+
+# Extract section grouping (Subdirectories + Workflow + Integration)
+# Reorder target to match, preserving custom sections
+
+# Before: Services > Deployment > Infrastructure > Utilities
+# After:  Services > Deployment > Infrastructure > Workflow > Integration Points > Utilities
+
+# All paths, tech names, and project context unchanged
+# Only organizational structure adopted from source
+```
+
+**Techniques:**
+- Load both target and source files and analyze their structure
+- Extract organizational patterns from source (not content or tech names)
+- Preserve target's technology names, paths, and project-specific context
+- Rewrite patterns using target's terminology and formatting
+- Maintain section order and hierarchy integrity
+- Commit before running and verify output

package/skills/instruction-guidelines/reference/simplify.md

@@ -0,0 +1,46 @@
+# simplify: Simplify Instruction Files
+
+**Guideline:** Reduce AGENTS.md/CLAUDE.md verbosity by 40-50% while preserving structure, workflows, and technology names.
+
+**Rationale:** Instruction files grow verbose over time. Simplification improves scannability and readability while preserving essential information, commands, and workflows needed for development.
+
+**Example:**
+
+```markdown
+# BEFORE (verbose, 145 lines)
+
+## Setup and Configuration
+
+The platform requires initialization through a multi-step process. First, you must install all necessary dependencies using the npm package manager. After installation, you should pull all large files from Git LFS to ensure you have the complete codebase available locally.
+
+The setup process involves:
+1. Running npm install to fetch all dependencies
+2. Running git lfs pull to download large binary files
+
+Once setup is complete, you can begin development work.
+
+## Running Tasks with Moon
+
+The project uses Moon as a task orchestration system. To run tasks, use the `npx moon run` command with the format `<project>:<task>`. You can also run tasks by tag using the `#<tag>:<task>` syntax...
+
+# AFTER (simplified, 80% reduction, 29 lines)
+
+## Setup
+
+- Dependencies → `npm install`
+- Large files → `git lfs pull`
+
+## Running Tasks
+
+- Project task → `npx moon run <project>:<task>`
+- Tag-based → `npx moon run #<tag>:<task>`
+- Tenants → `npx moon run #tenant-<name>:<task>`
+```
+
+**Techniques:**
+- Measure baseline line count to track reduction
+- Remove verbose prose and redundant descriptions
+- Condense multi-line bullets to single lines with inline details
+- Convert code blocks to inline arrow notation (`→`)
+- Preserve section hierarchy, technology names, and integration points
+- Keep command examples with actual tool names

package/skills/instruction-guidelines/reference/sync.md

@@ -0,0 +1,41 @@
+# sync: Sync AGENTS.md with Filesystem
+
+**Guideline:** Update AGENTS.md to reflect current directory structure, files, and configuration state while preserving technology names.
+
+**Rationale:** Directory structures evolve. Syncing keeps instruction files accurate and up-to-date with the actual filesystem state so developers have reliable reference documentation.
+
+**Example:**
+
+```markdown
+# Before sync (missing new directories)
+
+## Subdirectories
+- **services/**: TypeScript applications
+- **clusters/**: Kubernetes GitOps
+- **docs/**: Documentation
+
+# After scan, detect new directories
+# New: games/ (with C++, TypeScript), assets/, insights/
+
+# After sync (directories now reflect filesystem)
+
+## Subdirectories
+- **services/**: TypeScript/JavaScript apps (package.json, tsconfig.json)
+- **clusters/**: Kubernetes GitOps (kustomization.yaml)
+- **docs/**: Technical documentation (*.md)
+- **games/**: C++ game dev with TypeScript scripting (CMakeLists.txt, tsconfig.json)
+- **assets/**: Brand assets and fonts (*.ttf, *.png)
+- **insights/**: Development lessons (*.md)
+
+# Updated commands from detected config files
+# From moon.yml: "npx moon run <project>:<task>"
+# From package.json: "npm install", "npm run build"
+```
+
+**Techniques:**
+- Scan subdirectories 1 level deep, excluding node_modules, .git, build, dist
+- Identify config files (package.json, moon.yml, CMakeLists.txt, Dockerfile)
+- Format files inline: `(main.tf, vars, backend.sh)`
+- Detect `<name>/` patterns for similar directories
+- Add new directories, update existing entries, remove deleted ones
+- Extract updated commands from config files while preserving technology names

package/skills/kubernetes-guidelines/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: kubernetes-guidelines
+description: >-
+  Trigger on `.yaml/.yml` files in clusters/ or k8s directories. Use when writing Kubernetes manifests for GitOps deployments. Apply for Deployments, Services, security, multi-environment config. Keywords: Kubernetes, Deployment, Service, ConfigMap, Secret, Kustomize, Flux, RLS, SOPS, labels, namespaces.
+---
+
+# Kubernetes Coding Guidelines
+
+## Requirements
+
+- Kubernetes ≥ 1.28, Kustomize ≥ 5, GitOps (Flux).
+
+## Essentials
+
+- **Organization** - Use namespaces, labels, annotations consistently, see [reference/deployments.md](reference/deployments.md)
+- **Container images** - No `latest` tags, set requests/limits and probes, see [reference/deployments.md](reference/deployments.md)
+- **Security** - Run as non-root, read-only FS, drop capabilities, see [reference/deployments.md](reference/deployments.md)
+- **Configuration** - Use ConfigMaps/Secrets, SOPS/External Secrets for secrets, see [reference/configmaps-secrets.md](reference/configmaps-secrets.md)
+- **Multi-environment** - Manage with Kustomize bases/overlays, validate with `--dry-run`, see [reference/kustomize.md](reference/kustomize.md), [reference/validation.md](reference/validation.md)
+
+## Progressive disclosure
+
+- Read [reference/deployments.md](reference/deployments.md) - When creating or updating Deployment resources
+- Read [reference/services.md](reference/services.md) - When exposing applications or configuring load balancing
+- Read [reference/configmaps-secrets.md](reference/configmaps-secrets.md) - When externalizing configuration or managing secrets
+- Read [reference/kustomize.md](reference/kustomize.md) - When managing multiple environments with overlays
+- Read [reference/network-policies.md](reference/network-policies.md) - When implementing network isolation between pods
+- Read [reference/validation.md](reference/validation.md) - When validating manifests before applying to cluster