{
  "markdown": "<div align=\"center\">\n  <h1>docs-index-keeper</h1>\n  <p><strong>Keep your docs index in sync automatically.</strong></p>\n  <p>\n    <a href=\"https://www.npmjs.com/package/docs-index-keeper\"><img src=\"https://img.shields.io/npm/v/docs-index-keeper.svg\" alt=\"npm version\"></a>\n    <a href=\"https://www.npmjs.com/package/docs-index-keeper\"><img src=\"https://img.shields.io/npm/dm/docs-index-keeper.svg\" alt=\"npm downloads\"></a>\n    <a href=\"https://github.com/oleg-koval/docs-index-keeper/actions/workflows/ci.yml\"><img src=\"https://github.com/oleg-koval/docs-index-keeper/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"></a>\n    <a href=\"https://opensource.org/licenses/MIT\"><img src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License MIT\"></a>\n    <a href=\"https://nodejs.org\"><img src=\"https://img.shields.io/node/v/docs-index-keeper.svg\" alt=\"Node version\"></a>\n  </p>\n  <p>\n    <img src=\"https://img.shields.io/badge/skill-ready-0f766e\" alt=\"Skill ready\">\n    <img src=\"https://img.shields.io/badge/runtime-zero%20deps-1f2937\" alt=\"Zero deps\">\n    <img src=\"https://img.shields.io/badge/docs-index-automated-2563eb\" alt=\"Docs index automated\">\n    <img src=\"https://img.shields.io/badge/agent%20skills-open%20standard-059669\" alt=\"Agent Skills open standard\">\n    <img src=\"https://img.shields.io/badge/cursor-plugin%20ready-111827\" alt=\"Cursor plugin ready\">\n  </p>\n</div>\n\n**Keep your docs index in sync automatically.** When you add or change Markdown files under `docs/`, a pre-commit hook (or CI step) updates the index table—no manual edits, no forgotten entries.\n\n- **Zero config for common setups:** `docs/README.md` index, exclude `archive/`, optional warning for root-level `.md`\n- **Composable:** Use with [Husky](https://typicode.github.io/husky/) or plain `.git/hooks/pre-commit`\n- **CI-friendly:** `docs-index-keeper check` exits 1 if the index would change (enforce “index must be up to date”)\n- **Portable:** Node 18+, no runtime dependencies, works with npm / pnpm / yarn / bun\n\n---\n\n## Why use it?\n\n| Problem | What docs-index-keeper does |\n|--------|-----------------------------|\n| New runbooks or guides get added under `docs/` but nobody updates the index | Pre-commit (or CI) adds a row to `docs/README.md` automatically |\n| Contributors forget to touch the index | Hook runs on staged `.md` files; index is updated and re-staged in the same commit |\n| “Is this doc listed?” is a recurring review comment | Index stays in sync by construction |\n| Onboarding: “Where do I find X?” | Single table in `docs/README.md` is always up to date |\n\n**ROI:** A few minutes to run `npx docs-index-keeper init` once. After that, you avoid repeated manual index edits and review back-and-forth every time someone adds a doc. The index becomes a reliable map of your docs without extra process.\n\n---\n\n## Quick start\n\n```bash\n# In your repo root (with a docs/ folder and docs/README.md index table)\nnpm install -D docs-index-keeper\nnpx docs-index-keeper init\n```\n\nThen, when you `git add docs/my-new-guide.md` and commit, the hook will run `docs-index-keeper update` and add the new row to `docs/README.md` (and stage it).\n\n---\n\n## AI skill / marketplace readiness\n\nThis repository now includes a root [SKILL.md](./SKILL.md), which makes the project usable as an agent skill definition for skill-aware tools and registries that scan repository contents.\n\nWhat is included here:\n\n- `SKILL.md` with trigger phrases, workflow, config, and validation\n- richer Agent Skills metadata (`license`, `compatibility`, `metadata`)\n- a minimal Cursor plugin wrapper in [`.cursor-plugin/plugin.json`](./.cursor-plugin/plugin.json)\n- a Cursor skill layout in [`skills/docs-index-keeper/SKILL.md`](./skills/docs-index-keeper/SKILL.md)\n- npm package metadata that ships `SKILL.md` and usage examples\n- copy-pasteable prompts for agent tools in [examples/skill-usage.md](./examples/skill-usage.md)\n- a platform support note in [docs/agent-platforms.md](./docs/agent-platforms.md)\n\nWhat may still be needed:\n\n- some marketplaces require their own registry entry, plugin manifest, or catalog submission flow in addition to a repo-level `SKILL.md`\n- Cursor Marketplace publication still requires an actual plugin submission flow\n- if a directory or marketplace expects a different metadata schema, add that schema on top of this repo rather than replacing `SKILL.md`\n\n---\n\n## AI usage examples\n\n### Codex\n\n```text\nInstall docs-index-keeper in this repository, configure it for docs/README.md, add the pre-commit hook, and verify the setup.\n```\n\n```text\nUse docs-index-keeper to update the docs index for the currently staged Markdown files and show me which rows were added.\n```\n\n### Claude\n\n```text\nSet up docs-index-keeper in this repo so new docs under docs/ are automatically added to docs/README.md during pre-commit. Keep the default archive exclusion.\n```\n\n```text\nUse the docs-index-keeper workflow in this repository to add docs/runbooks/oncall.md into the docs index and explain any assumptions briefly.\n```\n\n### Cursor\n\n```text\nAdd docs-index-keeper to this project, wire the hook, and make CI fail if docs/README.md is missing entries for docs Markdown files.\n```\n\n### Platform support\n\n- Codex: `SKILL.md` plus `AGENTS.md`\n- Claude / Claude Code: `SKILL.md` plus repo-local guidance\n- Cursor: `SKILL.md` plus a minimal plugin manifest in `.cursor-plugin/plugin.json`\n\nDetails: [docs/agent-platforms.md](./docs/agent-platforms.md)\n\nMore examples: [examples/skill-usage.md](./examples/skill-usage.md)\n\nMarketplace submission checklist: [docs/marketplace-submissions.md](./docs/marketplace-submissions.md)\n\n---\n\n## Commands\n\n| Command | Purpose |\n|--------|---------|\n| `docs-index-keeper init` | Add a pre-commit hook (Husky or `.git/hooks/pre-commit`) that runs `update` and stages the index file |\n| `docs-index-keeper update` | Update the index from **staged** `.md` files (used by the hook) |\n| `docs-index-keeper check` | Dry run; exit 1 if the index would change (use in CI to require an up-to-date index) |\n| `docs-index-keeper add <path|mask...>` | Add one or many files to the index (e.g. `docs-index-keeper add docs/runbook.md docs/plans/*.md`) |\n\n---\n\n## Add One, Many, or by Mask\n\n`add` supports direct file paths and glob-like masks in one command.\n\n```bash\n# one file\ndocs-index-keeper add docs/runbook.md\n\n# many files\ndocs-index-keeper add docs/runbook.md docs/guides/oncall.md\n\n# mask (quote masks so your shell does not expand unexpectedly)\ndocs-index-keeper add \"docs/plans/*.md\"\n\n# mixed\ndocs-index-keeper add docs/README.md \"docs/plans/*.md\"\n```\n\nNotes:\n\n- only Markdown files are added\n- excluded paths are skipped based on config\n- already-indexed files are skipped\n- the command prints both added and skipped entries\n\n---\n\n## Config\n\nPut config in `package.json` or in `.docs-index-keeper.json` at the repo root.\n\n**Example (package.json):**\n\n```json\n{\n  \"docsIndexKeeper\": {\n    \"indexFile\": \"docs/README.md\",\n    \"docsDir\": \"docs\",\n    \"exclude\": [\"README.md\", \"archive/\"],\n    \"allowedRootMd\": [\"README.md\", \"AGENTS.md\", \"CONTRIBUTING.md\"],\n    \"warnRootMd\": true\n  }\n}\n```\n\n- **indexFile** — Path to the Markdown file that contains the index table (default: `docs/README.md`).\n- **docsDir** — Directory treated as “docs” (default: `docs`).\n- **exclude** — Paths under `docsDir` that are not added (e.g. `README.md`, `archive/`).\n- **allowedRootMd** — Root-level `.md` files that do not trigger a warning when changed.\n- **warnRootMd** — If `true`, warn when new/changed `.md` in repo root (or `.github/`) are staged; suggests moving them to `docs/`.\n\n---\n\n## Index format\n\nThe index file should contain a Markdown table with a header like `| Doc | Purpose |`. New rows are inserted before a “sentinel” row (e.g. `| [archive/](archive/) | … |`) or at the end of the table. The **title** for the link is taken from the filename; the **purpose** column uses the first `#` heading in the file, or a slugified filename.\n\n---\n\n## CI: require index up to date\n\n```yaml\n# .github/workflows/docs-index-check.yml\n- run: npm ci\n- run: npx docs-index-keeper check\n```\n\nUse `DOCS_INDEX_KEEPER_STAGED` to simulate staged files (e.g. in tests or CI):\n\n```bash\nDOCS_INDEX_KEEPER_STAGED=\"docs/foo.md\" npx docs-index-keeper check\n```\n\n---\n\n## Releases (maintainers)\n\n**Publishing is fully automated in GitHub Actions.**\n\n- Push a Conventional Commit to `main` for a stable release.\n- Push a Conventional Commit to `beta` for an installable npm pre-release published on the `beta` dist-tag.\n- Every push to `main` or `beta` first runs a release-readiness job that validates `NPM_TOKEN` and dry-runs `semantic-release` before the actual publish step runs.\n\n**One-shot: create repo, commit, push** (no local npm publish):\n\n```bash\n./publish.sh\n```\n\nRun from the package root. Requires `git`, `gh` (logged in), and `npm`. Overrides: `PROJECT_DIR`, `REUSE_REMOTE_REPO=true`, `COMMIT_MSG=\"...\"`. After push, CI performs the npm publish.\n\n- **Versioning:** Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:` → minor, `fix:` → patch, `BREAKING CHANGE:` (or `feat!:` / `fix!:`) → major.\n- **Pre-releases:** The `beta` branch publishes versions like `1.2.0-beta.1`. Install with `npm install docs-index-keeper@beta`.\n- **Changelog:** `CHANGELOG.md` is generated and maintained by the release workflow. Do not edit it manually.\n- **Secrets:** In the repo’s GitHub Settings → Secrets and variables → Actions, add **NPM_TOKEN** (npm token with **Read and write** for your packages). Paste the token with **no trailing newline or space**. Use `scripts/set-npm-token-secret.sh --from-browser` after creating a token at https://www.npmjs.com/settings/~/tokens (Granular). `GITHUB_TOKEN` is provided by Actions.\n- **Local verification:** Run `npm run release:dry-run` to validate the semantic-release setup locally without publishing.\n\n**Publishing to GitHub Package Registry (instead of npm):** Use a scoped name in `package.json` (e.g. `@oleg-koval/docs-index-keeper`) and add `\"publishConfig\": { \"registry\": \"https://npm.pkg.github.com\" }`. In CI, set the secret to a GitHub PAT with `write:packages` and use it as `NPM_TOKEN` (semantic-release/npm uses `NPM_TOKEN` for any registry). Install from GitHub: `npm install @oleg-koval/docs-index-keeper` with `.npmrc`: `@oleg-koval:registry=https://npm.pkg.github.com`.\n\n---\n\n## License\n\nMIT © [Oleg Koval](https://github.com/oleg-koval)\n",
  "bytes": 10413,
  "sha": "e885432591b4056f1e7d0319d11e0c580eb9653fa77e3e94137a173212be4f37",
  "repo_slug": "oleg-koval/docs-index-keeper",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_oleg_koval_docs_index_keeper_docs_index__6c1e0267/readme"
}