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

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,104 @@
+# 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
+
+Create or sign in to the npm account that owns the `@ghostbyte1014` scope. Confirm package-name 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 using the exact owner, repository, and workflow filename `.github/workflows/publish-npm.yml`. Configure a protected GitHub environment named `npm` if release approval is desired.
+
+After that, publish releases by updating the version, committing, creating a GitHub release, and allowing the workflow to use OIDC. No long-lived `NPM_TOKEN` is required.
+
+```powershell
+npm.cmd version patch
+git push --follow-tags
+$version = node -p "require('./package.json').version"
+gh release create "v$version" --generate-notes
+```
+
+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,11 @@
+# Release process
+
+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. Update the version with `npm version patch`, `minor`, or `major` according to compatibility.
+5. Push the commit and tag, then create the matching GitHub release.
+6. Let `.github/workflows/publish-npm.yml` publish through npm trusted publishing.
+7. Verify `npx --yes @ghostbyte/agent-docs-kit@<version> --help` from a clean directory.
+
+The first publish is manual because the npm package must exist before its trusted publisher can be configured.

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.