@ghostbyte/agent-docs-kit 0.0.0-stage → 4.0.2

package/docs/ARCHITECTURE.md

@@ -0,0 +1,107 @@
+# Architecture and file structure
+
+The repository separates executable behavior, canonical reference content, the installable skill, project templates, maintainer automation, tests, and the static website.
+
+```text
+Agent_Docs_Kit/
+├─ .github/
+│  └─ workflows/
+│     ├─ ci.yml                    # tests, validation, package smoke check
+│     ├─ pages.yml                 # GitHub Pages build and deployment
+│     └─ publish-npm.yml           # npm trusted-publishing release
+├─ bin/
+│  └─ agent-docs.mjs               # npm executable entry point
+├─ src/
+│  ├─ api/
+│  │  └─ index.mjs                 # programmatic public exports
+│  ├─ cli/
+│  │  ├─ arguments.mjs             # option and positional parsing
+│  │  ├─ help.mjs                  # command reference
+│  │  └─ main.mjs                  # direct-command and menu router
+│  ├─ commands/
+│  │  ├─ audit.mjs                 # docs/security report creation
+│  │  ├─ doctor.mjs                # prerequisite checks
+│  │  ├─ list.mjs                  # phase/topic discovery
+│  │  ├─ setup.mjs                 # project docs scaffold
+│  │  ├─ skill.mjs                 # explicit skill installation
+│  │  └─ validate.mjs              # package integrity checks
+│  └─ core/
+│     ├─ catalog.mjs               # canonical catalog loader
+│     ├─ files.mjs                 # safe write/copy primitives
+│     └─ paths.mjs                 # package-relative resolution
+├─ content/
+│  ├─ catalog.json                 # phase/topic IDs, slugs, sources
+│  ├─ security/
+│  │  ├─ 01-design-architecture.md
+│  │  ├─ ...                       # phases 02–11
+│  │  ├─ 12-ongoing-operations.md
+│  │  └─ full-reference.md         # deep lookup; not loaded by default
+│  └─ engineering/
+│     ├─ 01-query-performance.md
+│     ├─ ...                       # topics 02–08
+│     ├─ 09-message-queues.md
+│     └─ full-reference.md
+├─ skills/
+│  └─ manage-project-quality/
+│     ├─ agents/
+│     │  └─ openai.yaml            # skill UI metadata
+│     ├─ assets/
+│     │  ├─ documentation-report.md
+│     │  ├─ engineering-report.md
+│     │  └─ security-report.md
+│     ├─ references/
+│     │  ├─ documentation-governance.md
+│     │  ├─ engineering-protocol.md
+│     │  ├─ evidence-and-reporting.md
+│     │  ├─ security-protocol.md
+│     │  ├─ security-01-....md      # 12 progressive phase files
+│     │  └─ engineering-01-....md   # 9 progressive topic files
+│     ├─ scripts/
+│     │  └─ check-report.mjs
+│     └─ SKILL.md                   # concise routing instructions
+├─ scripts/
+│  ├─ build-site.mjs
+│  ├─ build-skill.mjs
+│  └─ validate-content.mjs
+├─ site/
+│  ├─ index.html
+│  └─ styles.css
+├─ tests/
+│  ├─ cli.test.mjs
+│  └─ content.test.mjs
+├─ build/                           # generated, ignored
+│  └─ site/
+├─ docs/
+│  ├─ ARCHITECTURE.md
+│  ├─ GITHUB_AND_NPM_SETUP.md
+│  ├─ PURPOSE.md
+│  ├─ RELEASE_PROCESS.md
+│  └─ SECURITY_MODEL.md
+├─ docs/archive/
+│  └─ AGENT_DOCS_KIT_v3.2.md        # retained legacy compiled edition
+├─ LICENSE
+├─ README.md
+└─ package.json
+```
+
+## Installed project structure
+
+`agent-docs setup` creates only the starting documents needed to establish ownership and navigation:
+
+```text
+.agent-docs/config.json
+docs/
+├─ README.md
+├─ 01-system/overview.md
+├─ 02-project/README.md
+├─ 03-development/
+│  └─ engineering-reviews/
+├─ 04-testing/
+│  ├─ security-audits/
+│  └─ evidence/
+├─ 05-operations/README.md
+├─ 06-future-enhancements/README.md
+└─ archive/README.md
+```
+
+The CLI creates audit reports beneath this tree. It does not copy the entire reference library into each consumer project.

package/docs/CONTENT_MAINTENANCE.md

@@ -0,0 +1,9 @@
+# Content maintenance
+
+The files under `content/` are canonical. Run `npm run build` after changing them so the installable skill receives the same progressive references.
+
+Review security guidance at least quarterly and after material changes to major standards, threat models, supported platforms, or tooling. Record the source and review date in the changed content or pull request. Verify external claims against primary sources.
+
+Review engineering topics when supported runtimes, architectural assumptions, or operational scale change. Keep recommendations contextual and avoid presenting preferences as universal rules.
+
+Before release, run the content validator. It checks catalog/source consistency and common encoding corruption. A human review is still required for technical accuracy and link freshness.

package/docs/GITHUB_AND_NPM_SETUP.md

@@ -0,0 +1,112 @@
+# GitHub and npm setup
+
+These commands assume the GitHub owner is `ghostbyte1014`, the repository is `Agent_Docs_Kit`, and the npm package is owned by the separate npm account `ghostbyte` at `@ghostbyte/agent-docs-kit`.
+
+## 1. Validate locally
+
+On Windows PowerShell, use `npm.cmd` if execution policy blocks `npm.ps1`:
+
+```powershell
+npm.cmd install
+npm.cmd test
+npm.cmd run validate
+npm.cmd run build
+npm.cmd pack --dry-run
+```
+
+## 2. Create and push the GitHub repository
+
+With GitHub CLI:
+
+```powershell
+git add .
+git commit -m "feat: unify Agent Docs and Quality Kit"
+gh auth login
+gh repo create ghostbyte1014/Agent_Docs_Kit --public --source . --remote origin --push
+```
+
+If `origin` already exists, inspect it before changing anything:
+
+```powershell
+git remote -v
+git push -u origin main
+```
+
+The web alternative is to create an empty repository on GitHub, then run:
+
+```powershell
+git remote add origin https://github.com/ghostbyte1014/Agent_Docs_Kit.git
+git branch -M main
+git push -u origin main
+```
+
+Do not add a second README, license, or `.gitignore` when creating the remote because this local repository already has them.
+
+## 3. Enable GitHub Pages
+
+The `pages.yml` workflow builds `build/site` and deploys it. In GitHub, open **Settings → Pages** and select **GitHub Actions** as the source. Then run the workflow or push to `main`.
+
+With GitHub CLI/API after the first push:
+
+```powershell
+gh api --method POST repos/ghostbyte1014/Agent_Docs_Kit/pages -f build_type=workflow
+gh workflow run pages.yml
+gh run watch
+```
+
+If Pages already exists with another source, use:
+
+```powershell
+gh api --method PUT repos/ghostbyte1014/Agent_Docs_Kit/pages -f build_type=workflow
+```
+
+## 4. Prepare npm
+
+Sign in to the npm account named `ghostbyte`, which owns the `@ghostbyte` personal scope. Confirm package access and authentication:
+
+```powershell
+npm.cmd view @ghostbyte/agent-docs-kit name version
+npm.cmd login
+npm.cmd whoami
+```
+
+An npm `E404` from `view` usually means no public package currently exists under that exact name; it does not prove that the signed-in account owns the scope.
+
+## 5. Publish the first version
+
+Review the archive before publishing:
+
+```powershell
+npm.cmd pack --dry-run
+npm.cmd publish --access public
+```
+
+The first publication establishes the package. Test it from a disposable directory:
+
+```powershell
+npx --yes @ghostbyte/agent-docs-kit@latest --help
+npx --yes @ghostbyte/agent-docs-kit@latest setup --dry-run
+```
+
+## 6. Configure trusted publishing
+
+In npm package settings, add a trusted publisher for GitHub Actions with these values:
+
+| Field | Value |
+|---|---|
+| Organization or user | `ghostbyte1014` |
+| Repository | `Agent_Docs_Kit` |
+| Workflow filename | `publish-npm.yml` |
+| Environment name | Leave blank |
+| Allowed actions | Allow direct `npm publish` |
+
+No npm token or GitHub environment is required. The workflow is restricted to this GitHub repository and workflow through OIDC.
+
+After that, commit your changes, increment the npm version, and push to `main`. The push automatically validates and publishes the new version. No long-lived `NPM_TOKEN` is required.
+
+```powershell
+npm.cmd version patch
+git push --follow-tags
+```
+
+Use `npm.cmd version minor` for a backward-compatible feature and `npm.cmd version major` for a breaking change. Never reuse an existing npm version: registry versions are immutable. Use `npm deprecate` for a bad release and publish a corrected version.

package/docs/PURPOSE.md

@@ -0,0 +1,23 @@
+# Purpose and boundaries
+
+Agent Docs & Quality Kit is a library and command-line interface for establishing repeatable project-quality practices. It unifies three related activities without pretending they have the same consequences.
+
+## Documentation
+
+The documentation workflow preserves project memory. It creates a predictable place for system facts, current scope, decisions, development records, test evidence, operations, future proposals, and superseded material. Its audit detects gaps and drift.
+
+Documentation is not a security boundary. A statement such as “change freeze is on” is a collaboration policy until a hook, branch rule, or CI check enforces it.
+
+## Security
+
+The security workflow assesses controls that protect confidentiality, integrity, availability, and privacy. It requires evidence for every verdict and distinguishes a real pass from an unverified condition. Critical and High failures are release blockers by default.
+
+Passive repository review is safe to start. Active testing of a running service, cloud account, network, credential, or production environment requires explicit authorization for the exact target.
+
+## Engineering
+
+The engineering workflow reviews practices that influence maintainability, reliability, performance, testability, operability, and cost. Its recommendations are contextual and normally non-blocking. A finding that is actually a vulnerability, correctness defect, or data-loss risk is reported separately with the appropriate urgency.
+
+## Interaction styles
+
+`standard` produces concise findings and actions. `learning` adds why a control matters and a practical example. Both modes use the same evidence rules and verdicts.

package/docs/RELEASE_PROCESS.md

@@ -0,0 +1,22 @@
+# Release process
+
+Published npm versions are immutable. A push can publish a new version, but it cannot replace the contents of an existing version.
+
+1. Update canonical content and run `npm run build` to refresh progressive skill references and the site.
+2. Run `npm test`, `npm run validate`, and `npm pack --dry-run`.
+3. Confirm the package archive contains no credentials, local reports, nested repositories, or generated consumer data.
+4. Commit the package changes locally.
+5. Update the version with `npm version patch`, `minor`, or `major` according to compatibility.
+6. Push the commit and tag. A push to `main` runs `.github/workflows/publish-npm.yml` and publishes the new version through npm trusted publishing.
+7. Verify `npx --yes @ghostbyte/agent-docs-kit@<version> --help` from a clean directory.
+
+```powershell
+git add -A
+git commit -m "feat: describe the update"
+npm.cmd version patch
+git push --follow-tags
+```
+
+Use `minor` for a backward-compatible feature and `major` for a breaking change. A GitHub Release is optional and does not control npm publication.
+
+The first release was published manually because the package had to exist before its trusted publisher could be configured. If a pushed version already exists, the workflow validates the project and safely skips publication; increment the version before pushing package changes that should reach npm.

package/docs/SECURITY_MODEL.md

@@ -0,0 +1,9 @@
+# Security model
+
+The CLI is inert on installation: `package.json` defines no `preinstall`, `install`, or `postinstall` script. Explicit commands are required to create files.
+
+Project setup skips existing files by default. `--force` is required to replace files owned by a command, and `--dry-run` previews writes. The package does not install Git hooks automatically, execute network scans, read credentials, or contact a telemetry service.
+
+Audit reports begin as `Unverified`. The tool scaffolds the review; it does not claim that generated text proves a control. Agents and reviewers must attach repository paths, line numbers, reproducible command output, or authorized external evidence.
+
+Publishing uses npm provenance through GitHub trusted publishing when configured. Protect the GitHub release environment, require reviews as appropriate, and never store a long-lived npm token when OIDC is available.

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@ghostbyte/agent-docs-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.0.2",
+  "description": "Documentation governance, evidence-based security audits, and engineering-quality reviews for software projects.",
+  "type": "module",
+  "bin": {
+    "agent-docs": "bin/agent-docs.mjs"
+  },
+  "exports": {
+    ".": "./src/api/index.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "content/",
+    "templates/",
+    "skills/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build-site.mjs && node scripts/build-skill.mjs",
+    "site:preview": "node scripts/preview-site.mjs",
+    "doctor": "node bin/agent-docs.mjs doctor",
+    "test": "node --test",
+    "validate": "node scripts/validate-content.mjs && node bin/agent-docs.mjs validate",
+    "prepublishOnly": "npm run build && npm test && npm run validate"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "ai-agent",
+    "documentation",
+    "security-audit",
+    "engineering-review",
+    "quality"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ghostbyte1014/Agent_Docs_Kit.git"
+  },
+  "homepage": "https://ghostbyte1014.github.io/Agent_Docs_Kit/",
+  "bugs": {
+    "url": "https://github.com/ghostbyte1014/Agent_Docs_Kit/issues"
+  },
+  "license": "MIT",
+  "author": "ghostbyte1014",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "serve.js",
+  "directories": {
+    "doc": "docs",
+    "test": "tests"
+  }
+}

package/skills/manage-project-quality/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: manage-project-quality
+description: Set up and audit project documentation, perform evidence-based security reviews, or assess engineering practices. Use when asked to create or repair a docs structure, check documentation drift, conduct a security gate or phase audit, review engineering quality, generate audit evidence, or explain Agent Docs & Quality Kit results in standard or learning mode.
+---
+
+# Manage Project Quality
+
+Choose exactly one primary workflow for the request: documentation governance, security assurance, or engineering review. Combine workflows only when the user explicitly requests a broader quality pass.
+
+## Establish the operating context
+
+1. Inspect the repository, its local instructions, and the files relevant to the request.
+2. State the target, scope, exclusions, and interaction style before changing files.
+3. Use `standard` style by default. Use `learning` style when the user asks to learn; explain why each important control matters without inflating routine output.
+4. Preview file creation or replacement. Preserve unrelated user changes and do not overwrite an existing report unless explicitly authorized.
+5. Cite repository evidence with paths and line numbers. Use command output or external-system evidence when a file cannot establish the result.
+
+## Route the request
+
+### Documentation governance
+
+Read [references/documentation-governance.md](references/documentation-governance.md). Use it to establish a navigable documentation structure, identify stale or missing material, separate current scope from future ideas, and preserve decision/change history.
+
+Documentation controls are governance aids, not an infallible technical lock. Report whether evidence supports the stated process; never claim that Markdown alone enforces agent behavior.
+
+### Security assurance
+
+Read [references/security-protocol.md](references/security-protocol.md), [references/evidence-and-reporting.md](references/evidence-and-reporting.md), and only the selected phase references below.
+
+Passive source and configuration review may proceed within the user-provided repository. Before scanning a live target, sending crafted traffic, exercising credentials, changing cloud resources, or running any potentially disruptive test, obtain explicit authorization for the exact target and prefer a non-production environment.
+
+Use only `Pass`, `Fail`, `Unverified`, or `N/A`. A missing observable is `Unverified`, not `Pass` or `N/A`. Treat unresolved Critical or High failures as release blockers unless an accountable owner records a time-bounded exception.
+
+### Engineering review
+
+Read [references/engineering-protocol.md](references/engineering-protocol.md), [references/evidence-and-reporting.md](references/evidence-and-reporting.md), and only the selected topic references below.
+
+Use `Applied`, `Partial`, `Recommended`, `Unverified`, or `N/A`. Engineering recommendations are normally advisory. Clearly separate them from security gates, correctness defects, and release blockers.
+
+## Security phase references
+
+- [01 Design & Architecture](references/security-01-design-architecture.md)
+- [02 Local Development](references/security-02-local-development.md)
+- [03 Database & Backend](references/security-03-database-backend.md)
+- [04 API Layer](references/security-04-api-layer.md)
+- [05 Frontend & UI](references/security-05-frontend-ui.md)
+- [06 Application Security Testing](references/security-06-application-security-testing.md)
+- [07 CI/CD & Release Engineering](references/security-07-cicd-release-engineering.md)
+- [08 Cloud Infrastructure](references/security-08-cloud-infrastructure.md)
+- [09 Edge, CDN & DNS](references/security-09-edge-cdn-dns.md)
+- [10 Release & Rollout](references/security-10-release-rollout.md)
+- [11 Post-release Monitoring & Incident Response](references/security-11-post-release-monitoring-ir.md)
+- [12 Ongoing Operations](references/security-12-ongoing-operations.md)
+- [Full security reference](references/security-full-reference.md): search by heading or control name; do not load the entire file unless the user requests a full audit.
+
+## Engineering topic references
+
+- [01 Query Performance](references/engineering-01-query-performance.md)
+- [02 Networking Fundamentals](references/engineering-02-networking-fundamentals.md)
+- [03 Rate Limiting Algorithms](references/engineering-03-rate-limiting-algorithms.md)
+- [04 Production Debugging](references/engineering-04-production-debugging.md)
+- [05 Code Review Practices](references/engineering-05-code-review-practices.md)
+- [06 Data Modeling](references/engineering-06-data-modeling.md)
+- [07 Cloud Cost Saving](references/engineering-07-cloud-cost-saving.md)
+- [08 Testing Types](references/engineering-08-testing-types.md)
+- [09 Message Queues](references/engineering-09-message-queues.md)
+- [Full engineering reference](references/engineering-full-reference.md): use only for cross-topic review.
+
+## Produce the result
+
+1. Record scope, date, reviewer, interaction style, and evidence limitations.
+2. Assign a status only after collecting evidence.
+3. Rank findings by impact and confidence. Separate observed facts from inference.
+4. Give a concrete remediation, owner, and verification step for each actionable finding.
+5. Summarize blockers first, then non-blocking improvements, then unverified items.
+6. Never expose secrets in output. Redact tokens, credentials, personal data, and sensitive endpoints.
+
+Use [assets/security-report.md](assets/security-report.md), [assets/engineering-report.md](assets/engineering-report.md), or [assets/documentation-report.md](assets/documentation-report.md) when writing a report. Run `node scripts/check-report.mjs <report>` to catch invalid statuses and findings without evidence.

package/skills/manage-project-quality/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Agent Docs & Quality"
+  short_description: "Govern docs and review project quality"
+  default_prompt: "Use $manage-project-quality to set up project documentation or run an evidence-based security or engineering review."

package/skills/manage-project-quality/assets/documentation-report.md

@@ -0,0 +1,12 @@
+# Documentation audit: {{scope}}
+
+- Date: {{date}}
+- Reviewer: {{reviewer}}
+
+| Document or rule | Status | Evidence | Required update |
+|---|---|---|---|
+| | Unverified | | |
+
+## Missing or conflicting authorities
+
+Record gaps, duplicate sources of truth, stale content, and broken navigation.

package/skills/manage-project-quality/assets/engineering-report.md

@@ -0,0 +1,13 @@
+# Engineering review: {{scope}}
+
+- Date: {{date}}
+- Reviewer: {{reviewer}}
+- Overall status: Unverified
+
+| Practice | Status | Evidence | Impact | Recommendation / verification |
+|---|---|---|---|---|
+| | Unverified | | | |
+
+## Priority recommendations
+
+Record the highest-value improvements and their expected tradeoffs.

package/skills/manage-project-quality/assets/security-report.md

@@ -0,0 +1,18 @@
+# Security audit: {{scope}}
+
+- Date: {{date}}
+- Reviewer: {{reviewer}}
+- Authorized target: {{target}}
+- Overall status: Unverified
+
+| Control | Severity | Status | Evidence | Remediation / verification |
+|---|---|---|---|---|
+| | | Unverified | | |
+
+## Release blockers
+
+None established yet.
+
+## Limitations and exceptions
+
+Record unavailable external evidence and approved, time-bounded risk exceptions.

package/skills/manage-project-quality/references/documentation-governance.md

@@ -0,0 +1,39 @@
+# Documentation governance
+
+## Purpose
+
+Documentation governance keeps project intent, implementation facts, decisions, and operating knowledge findable and current. It reduces context loss for humans and agents. It does not, by itself, prevent repository mutation.
+
+## Recommended project layout
+
+```text
+.agent-docs/
+  config.json
+docs/
+  README.md
+  01-system/
+  02-project/
+  03-development/
+    audits/
+    engineering-reviews/
+  04-testing/
+    security-audits/
+    evidence/
+  05-operations/
+  06-future-enhancements/
+  archive/
+```
+
+Keep the layout proportional to the project. Do not create empty documents merely to satisfy a tree. Every index must describe what belongs beneath it and identify authoritative documents.
+
+## Audit sequence
+
+1. Locate local instructions and the documentation index.
+2. Compare claimed behavior with code, configuration, tests, and deployment files.
+3. Find broken links, duplicate authorities, stale dates, unresolved placeholders, and undocumented operational dependencies.
+4. Classify each document as `Current`, `Needs update`, `Reference`, or `Archived`.
+5. Propose the smallest repair that restores a single clear source of truth.
+
+## Change records
+
+Record what changed, why it changed, files affected, validation performed, and approval when required by the project. Prefer commit-linked records. Treat a “change freeze” as a declared collaboration policy unless a technical hook or CI rule actually enforces it.

package/skills/manage-project-quality/references/engineering-01-query-performance.md

@@ -0,0 +1,48 @@
+# Query Performance & Slow Query Diagnosis
+
+# Engineering Topic 1: Query Performance & Slow Query Diagnosis
+
+**When to run this:** When a query, endpoint, or report is running slower than expected, or before shipping a new query against a table that will grow.
+
+**Goal of this pass:** Work through the standard diagnostic order for a slow query instead of guessing at fixes — read the plan first, fix the cheapest thing, and don't reach for denormalization until indexing is exhausted.
+
+## Files in this folder
+
+| File | Purpose |
+|---|---|
+| `CHECKLIST.md` | The reference list of concepts for this topic — what each one is, why it matters, and the self-check question to ask. Doesn't get filled in; copy `RESULTS_TEMPLATE.md` to record a real pass. |
+| `RESULTS_TEMPLATE.md` | Fillable version of the same list, with a Status column and notes. Copy this file per pass (e.g. `RESULTS_2026-08-29.md`) so history isn't overwritten. |
+
+Full source list lives in `../ENGINEERING_REFERENCE.md`. Unlike
+`../../security-gate/phases/`, this is knowledge/practice review, not pass/fail security
+testing — there's no severity rating, and "Fail" isn't the right framing.
+Use the Status options in `RESULTS_TEMPLATE.md` instead: Applied, Partial,
+Should adopt, or Not applicable.
+
+## Wrap-up
+
+- This isn't a gate — nothing here blocks a release the way
+  Critical/High security items in `../../security-gate/phases/` do.
+- Total concepts in this topic: 10
+- Useful as an onboarding read-through, a periodic self-audit, or context
+  to hand an agent before it reviews related code.
+
+---
+
+# Concepts — Topic 1: Query Performance & Slow Query Diagnosis
+
+Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
+this same folder to actually record a pass.
+
+| # | Concept | Why it matters | Self-check |
+|---|---|---|---|
+| 1 | Start with the explain plan | Reveals whether the DB is scanning, sorting, or joining in a way that doesn't match intent — guessing at fixes without this wastes time. | Have you run EXPLAIN (or EXPLAIN ANALYZE) on the slow query and read where the time actually goes? |
+| 2 | Add the missing index | Full table scans get linearly worse as data grows; the right index turns O(n) into O(log n). | Does the WHERE/JOIN/ORDER BY column set have a supporting index? |
+| 3 | Stop selecting * | Pulling unused columns wastes I/O and network, and can defeat a covering index. | Does the query request only the columns actually used downstream? |
+| 4 | Fix N+1 queries | One query per row in a loop turns a single request into hundreds; batching/joining collapses it back to one or few. | Does any code path issue a query inside a loop over another query's results? |
+| 5 | Use a covering index | An index that includes all selected columns lets the DB answer from the index alone, skipping the table lookup. | For hot read queries, does the index include every column the query selects? |
+| 6 | Cache repeated queries | Identical, expensive, low-volatility queries don't need to hit the DB every time. | Are the same expensive read queries re-run frequently with unchanged results, and if so, are they cached? |
+| 7 | Prune partitions | Partition pruning lets the DB skip irrelevant partitions entirely instead of scanning the whole table. | For large time-series/partitioned tables, does the query filter on the partition key so pruning can kick in? |
+| 8 | Denormalize for reads | Trading write complexity/redundancy for fewer joins can be the right call once indexing alone isn't enough. | Has indexing been exhausted before reaching for denormalization, and is the redundancy kept in sync deliberately? |
+| 9 | Batch your writes | Many small write round-trips cost more in overhead than one larger batched write. | Are writes that happen together (e.g. in a loop or transaction) batched instead of issued one at a time? |
+| 10 | Update table statistics | A stale planner (out-of-date row-count/distribution stats) can pick a bad plan even with the right indexes present. | Are table statistics refreshed on a schedule (ANALYZE / equivalent), especially after large data changes? |

package/skills/manage-project-quality/references/engineering-02-networking-fundamentals.md

@@ -0,0 +1,48 @@
+# Networking Fundamentals
+
+# Engineering Topic 2: Networking Fundamentals
+
+**When to run this:** When debugging connectivity, latency, or TLS issues, or before making infra decisions (load balancer, CDN, multi-region) that depend on understanding the network path.
+
+**Goal of this pass:** Confirm the team can reason about what happens between a client request and a server response — not memorize trivia, but recognize which layer a given production issue actually lives in.
+
+## Files in this folder
+
+| File | Purpose |
+|---|---|
+| `CHECKLIST.md` | The reference list of concepts for this topic — what each one is, why it matters, and the self-check question to ask. Doesn't get filled in; copy `RESULTS_TEMPLATE.md` to record a real pass. |
+| `RESULTS_TEMPLATE.md` | Fillable version of the same list, with a Status column and notes. Copy this file per pass (e.g. `RESULTS_2026-08-29.md`) so history isn't overwritten. |
+
+Full source list lives in `../ENGINEERING_REFERENCE.md`. Unlike
+`../../security-gate/phases/`, this is knowledge/practice review, not pass/fail security
+testing — there's no severity rating, and "Fail" isn't the right framing.
+Use the Status options in `RESULTS_TEMPLATE.md` instead: Applied, Partial,
+Should adopt, or Not applicable.
+
+## Wrap-up
+
+- This isn't a gate — nothing here blocks a release the way
+  Critical/High security items in `../../security-gate/phases/` do.
+- Total concepts in this topic: 10
+- Useful as an onboarding read-through, a periodic self-audit, or context
+  to hand an agent before it reviews related code.
+
+---
+
+# Concepts — Topic 2: Networking Fundamentals
+
+Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
+this same folder to actually record a pass.
+
+| # | Concept | Why it matters | Self-check |
+|---|---|---|---|
+| 1 | DNS resolution | Wrong TTLs or stale records cause outages/slow failover that look like application bugs. | Do you know your DNS TTLs and what happens on a DNS provider outage or a failed cutover? |
+| 2 | TCP handshake | SYN/SYN-ACK/ACK latency adds to every new connection; connection reuse avoids paying it repeatedly. | Are connections being reused (keep-alive/pooling) where the handshake cost matters? |
+| 3 | TLS handshake | Adds round trips and CPU cost on top of TCP; session resumption and TLS version choice affect both. | Is TLS session resumption enabled, and is the minimum TLS version intentionally set? |
+| 4 | NAT | Explains why a server sees one client IP for many real users, and why some P2P/inbound-connection patterns don't work as expected. | Does any rate-limiting or per-client logic depend on client IP, and does it account for NAT'd clients sharing an IP? |
+| 5 | Load balancer types | L4 vs L7 balancers differ in what they can inspect and route on (raw TCP vs HTTP headers/paths). | Does the current load balancer type actually support the routing/health-check behavior the app needs? |
+| 6 | CDN edge caching | Wrong cache-control headers cause either stale content served for too long or origin overload from no caching at all. | Are cache-control/CDN cache-key rules deliberately set per route, not left at CDN defaults? |
+| 7 | Packet loss & retransmit | Retransmits show up as latency and timeouts that look application-side but are actually network-layer. | When debugging intermittent slowness, has packet loss been ruled out before blaming application code? |
+| 8 | MTU / fragmentation | Oversized packets get fragmented or dropped, which shows up as weird partial-failure behavior, especially over VPNs/tunnels. | Has MTU mismatch been considered for any VPN, tunnel, or container network path in play? |
+| 9 | Keep-alive | Persistent connections avoid the handshake cost per request but tie up server resources if left open too long. | Are keep-alive timeouts tuned deliberately on both client and server, not left at framework defaults? |
+| 10 | BGP routing | Explains internet-scale outages and route leaks — usually outside your control, but recognizable when it's the actual cause. | When a broad, upstream-looking outage occurs, is BGP/routing considered as a possible cause rather than assumed to be your infra? |