@open-agent-toolkit/cli 0.1.21 → 0.1.22

package/assets/skills/authoring-docs/references/categories.md

@@ -0,0 +1,251 @@
+---
+title: Documentation Categories
+description: Category-specific guidance for APIs, CLIs, apps, services, libraries, frameworks, monorepos, architecture, operations, and audience boundaries.
+---
+
+# Documentation Categories
+
+Use category guidance after classifying the project. A repository can belong to
+multiple categories; document the dominant reader path first, then add focused
+reference, operational, or conceptual pages where the evidence supports them.
+
+## APIs
+
+API docs must help consumers integrate correctly without reading implementation
+code.
+
+Document:
+
+- overview and use cases
+- base URL, service location, or schema source
+- environments
+- authentication and authorization
+- request and response formats
+- status codes and error shape
+- pagination, filtering, sorting, and limits
+- idempotency, retries, and timeouts
+- versioning, deprecation, and compatibility behavior
+- webhooks, events, SDKs, or generated clients when applicable
+- examples grounded in real routes, schemas, or tests
+- support, ownership, or escalation when known
+
+For REST or HTTP APIs, document method, path, side effects, auth requirement,
+path and query parameters, request headers, request body, response body, status
+codes, error codes, example request, example response, retry behavior,
+idempotency, pagination, and deprecation notes.
+
+For GraphQL, include endpoint, auth, schema source, common queries and
+mutations, variables, fragments, pagination, errors, nullability, query cost or
+depth limits, and deprecation policy.
+
+For event-driven APIs, document event name, producer, known consumers,
+transport, topic or stream, schema, example payload, ordering guarantees,
+delivery guarantees, retry behavior, dead-letter behavior, idempotency
+requirements, versioning, and backward compatibility.
+
+For webhooks, document event types, endpoint expectations, signing and
+verification, retry schedule, timeout, payload schema, idempotency, ordering,
+testing tools, replay behavior, and security considerations.
+
+Prefer machine-readable schemas where the repo has them: OpenAPI, GraphQL,
+AsyncAPI, JSON Schema, Protocol Buffers, or generated types. Pair generated
+reference with hand-written onboarding and workflow guides.
+
+## CLIs
+
+CLI docs must help readers run the right command safely. A CLI is both a human
+interface and an automation interface.
+
+Document:
+
+- installation
+- authentication
+- configuration and precedence
+- quick start
+- common workflows
+- command reference
+- arguments, flags, inherited flags, aliases, and defaults
+- environment variables and config files
+- output formats and machine-readable output
+- exit codes
+- prompts and non-interactive behavior
+- CI and scripting behavior
+- logging, verbosity, retries, and timeouts
+- dry-run behavior when supported
+- production safety notes
+- troubleshooting
+
+For each command, include purpose, usage syntax, examples, side effects, output
+shape, JSON shape if supported, exit codes, related commands, and any
+environment or config keys it reads.
+
+Do not invent exit codes. If exit codes are not explicit in source or docs, say
+they are not documented.
+
+## Apps and Services
+
+Application and service docs should help people understand, run, change,
+deploy, operate, and recover the system.
+
+All apps and services should document:
+
+- purpose, audience, and users
+- local development
+- testing
+- configuration
+- dependencies
+- deployment
+- observability
+- ownership
+- troubleshooting
+- architecture summary
+- operational risks
+
+Frontend app docs should include routes, rendering model, data fetching, state
+management, design system usage, feature flags, analytics, accessibility,
+performance constraints, error boundaries, testing, local development, and
+deployment.
+
+Backend service docs should include service purpose, runtime, APIs, jobs,
+queues, databases, caches, external services, configuration, auth, local
+development, testing, deployment, observability, failure modes, and runbooks.
+
+Worker and job docs should include trigger, input payload, output or side
+effect, queue or scheduler, retry policy, timeout, concurrency, idempotency,
+dead-letter behavior, observability, replay process, and failure modes.
+
+Deployment docs should include where the system runs, deployment trigger,
+environments, required permissions, pre-deploy checks, deployment steps,
+post-deploy verification, rollback, and known risks.
+
+Troubleshooting pages should be symptom-first and map symptoms to likely cause,
+check, fix, and escalation.
+
+## Libraries, Packages, SDKs, and Frameworks
+
+Library and framework docs should help users decide whether to use the tool,
+install it, learn the mental model, apply it correctly, and avoid misuse.
+
+Document:
+
+- purpose
+- when to use it
+- when not to use it
+- installation
+- version compatibility and peer dependencies
+- quick start
+- core concepts
+- supported public API
+- examples and recipes
+- configuration
+- extension points
+- errors and side effects
+- testing guidance
+- migration guides
+- release policy
+- ownership and support model
+
+Document only supported public API unless the repository explicitly treats an
+internal surface as supported. For functions, classes, components, hooks, or
+types, include purpose, signature, parameters, return value, errors, examples,
+side effects, stability, and deprecation notes.
+
+Frameworks need stronger conceptual docs than small libraries: design goals,
+mental model, conventions, lifecycle, plugin model, file structure,
+configuration model, defaults, escape hatches, anti-patterns, migrations, and
+examples.
+
+Component libraries should document import path, props, examples, states,
+accessibility, design tokens, composition patterns, and when not to use a
+component.
+
+SDK docs should cover install, auth, client creation, common workflows, errors,
+retries, pagination, async behavior, type generation, version compatibility,
+and parity with the underlying service.
+
+## Monorepos
+
+Monorepo docs should help readers find the right package, app, service, or
+workflow without already knowing the source tree.
+
+Document:
+
+- repo purpose and major workspaces
+- package manager and workspace commands
+- build, test, lint, and type-check strategy
+- dependency graph or ownership map when available
+- shared config and conventions
+- release or deployment boundaries
+- how to run one package or app
+- how to add a new package or app
+- generated artifacts and source-of-truth boundaries
+- cross-package compatibility requirements
+
+Avoid organizing docs only by implementation directory. Prefer audience,
+product area, or workflow groupings, then link to package-level reference.
+
+## Architecture and Operations
+
+Architecture docs explain how the system works and why it is designed that way.
+Operations docs explain how to run, observe, debug, recover, and safely change
+the system.
+
+Architecture docs should answer:
+
+- What problem does this system solve?
+- What are the main components?
+- How does data flow through the system?
+- What are the boundaries?
+- What depends on this system, and what does it depend on?
+- What tradeoffs and decisions shaped the design?
+- What failure modes exist?
+- What should future maintainers avoid breaking?
+
+Use diagrams to clarify relationships, not to decorate. Every diagram should
+have a title, purpose, scope, explanation, caveats, and last verified date when
+it is highly operational.
+
+Use architecture decision records for significant decisions such as database
+choice, queueing model, API versioning, cache invalidation, auth model,
+deployment topology, framework choice, migration strategy, or deprecation
+strategy.
+
+Operations docs should answer:
+
+- Where does this run?
+- How is it deployed and rolled back?
+- How do I know it is healthy?
+- Where are logs, metrics, traces, dashboards, and alerts?
+- What are common failure modes?
+- How do I recover from them?
+- Who owns escalation?
+
+Runbooks should include symptoms, impact, checks, mitigation, verification,
+rollback, escalation, and known false positives. Alert docs should make every
+alert actionable. Rollback docs must include exact steps or explicitly say the
+rollback process is not documented.
+
+## Internal and Public Docs
+
+Internal and public docs share the same quality bar. The differences are
+audience, assumptions, security, and support model.
+
+Internal docs can include internal service names, environments, dashboards,
+alerts, runbooks, deployment workflows, known consumers, support channels, and
+escalation paths. They must not include secrets, credentials, tokens, private
+keys, sensitive customer data, personal data, or private incident details that
+do not belong in durable docs.
+
+Public docs should include purpose, onboarding, installation, authentication
+setup, permissions, examples, API or CLI reference, version compatibility,
+migration guides, deprecation policy, support path, security guidance, and
+accessibility or privacy notes when relevant.
+
+Public docs should avoid internal URLs, private dashboards, Slack links,
+deployment internals, customer-specific data, unapproved roadmap statements,
+and implementation details that are not part of the public contract.
+
+When converting internal docs to public docs, identify internal-only content,
+remove or rewrite sensitive details, replace examples with public-safe values,
+ensure links are public, remove private operational links, preserve user-facing
+behavior, and add a public support path.

package/assets/skills/authoring-docs/references/information-architecture.md

@@ -0,0 +1,156 @@
+---
+title: Information Architecture
+description: Standard documentation structure, naming, navigation, and cross-linking.
+---
+
+# Information Architecture
+
+Documentation structure should feel predictable across repositories even when
+the systems differ. Consistency makes docs easier to browse, review, migrate,
+and use as agent context.
+
+## Standard Top-Level Model
+
+Use this conceptual model:
+
+```txt
+Start here
+How-to guides
+Reference
+Concepts
+Operations
+```
+
+These labels map to reader needs:
+
+| Product Label | Documentation Type       | Reader Question                              |
+| ------------- | ------------------------ | -------------------------------------------- |
+| Start here    | Tutorial and orientation | What is this and how do I begin?             |
+| How-to guides | How-to                   | How do I complete this task?                 |
+| Reference     | Reference                | What are the exact facts?                    |
+| Concepts      | Explanation              | How does this work and why?                  |
+| Operations    | How-to plus reference    | How do I run, observe, fix, or recover this? |
+
+## Default Repo Structure
+
+```txt
+docs/
+├── index.md
+├── getting-started.md
+├── how-to/
+│   ├── local-development.md
+│   ├── testing.md
+│   ├── deployment.md
+│   └── troubleshooting.md
+├── reference/
+│   ├── configuration.md
+│   ├── environment-variables.md
+│   ├── commands.md
+│   ├── api.md
+│   └── errors.md
+├── concepts/
+│   ├── architecture.md
+│   ├── data-flow.md
+│   ├── auth.md
+│   └── caching.md
+└── operations/
+    ├── runbook.md
+    ├── observability.md
+    ├── alerts.md
+    └── rollback.md
+```
+
+Do not create empty pages for symmetry. Use the structure as a guide, not
+theater.
+
+## Scale the Structure to the Repo
+
+Tiny repos can use a single `README.md` if it covers purpose, install or setup,
+usage, configuration, testing, and ownership.
+
+Small repos should separate overview, usage, and reference.
+
+Medium repos should use the standard structure.
+
+Large repos or platforms can group by product area or audience, but should keep
+the same doc types recognizable. Avoid organizing only by implementation
+directory; readers usually do not arrive knowing the source tree.
+
+## Landing Page Contract
+
+Every docs entry point should answer:
+
+1. What is this?
+2. Why does it exist?
+3. Who is it for?
+4. What are the main capabilities?
+5. What are the boundaries and non-goals?
+6. How do I get started?
+7. What are the common tasks?
+8. Where is the reference material?
+9. How is it operated?
+10. Who owns it?
+
+## Navigation Principles
+
+Use predictable labels:
+
+- Getting started
+- Local development
+- Testing
+- Deployment
+- Configuration
+- Environment variables
+- API reference
+- CLI reference
+- Architecture
+- Data flow
+- Authentication
+- Observability
+- Troubleshooting
+- Runbook
+- Rollback
+
+Avoid clever labels such as `Misc`, `Magic`, `Deep cuts`, or `Everything else`.
+
+## Page Naming
+
+Use task names for how-to guides:
+
+```txt
+how-to/add-a-new-route.md
+how-to/deploy-to-production.md
+how-to/rotate-api-credentials.md
+```
+
+Use topic names for concepts:
+
+```txt
+concepts/authentication.md
+concepts/event-delivery.md
+concepts/caching.md
+```
+
+Use noun names for reference:
+
+```txt
+reference/environment-variables.md
+reference/cli.md
+reference/api.md
+reference/errors.md
+```
+
+## Cross-Linking Rules
+
+Link between doc types intentionally.
+
+A tutorial should link to related how-to guides, relevant reference pages, and
+conceptual background for later learning.
+
+A how-to guide should link to reference pages for options, concepts for why the
+task works, and operations pages for production safety.
+
+A reference page should link to tutorials or how-to guides that show common use.
+
+An explanation page should link to runbooks, deployment guides, API or CLI
+reference, and ADRs when available.

package/assets/skills/authoring-docs/references/page-types.md

@@ -0,0 +1,119 @@
+---
+title: Documentation Page Types
+description: Guidance for tutorials, how-to guides, reference docs, explanations, and runbooks.
+---
+
+# Documentation Page Types
+
+Most documentation problems come from mixing different kinds of information into
+one page. A page can contain supporting material from another type, but it
+should have one primary job.
+
+## Tutorial
+
+A tutorial teaches through a guided path. Use tutorials when the reader is new
+to the project or workflow.
+
+Good tutorial topics include running the app locally for the first time,
+sending the first API request, running the first CLI command, creating the first
+integration, making the first contribution, or deploying to a non-production
+environment.
+
+Rules:
+
+- Assume the reader is capable but unfamiliar with this system.
+- State prerequisites before steps.
+- Use one successful path.
+- Avoid branching.
+- Show expected output.
+- Explain only enough to keep the reader oriented.
+- End with a working result.
+- Link to deeper docs for next steps.
+
+## How-To Guide
+
+A how-to guide helps a reader complete a specific task.
+
+Good how-to topics include adding a route, adding a CLI command, rotating a
+secret, deploying a service, running a migration, debugging a worker, adding a
+feature flag, creating a webhook consumer, or onboarding a service consumer.
+
+Rules:
+
+- Title the page as a task.
+- Start with when to use the guide.
+- State prerequisites.
+- Use numbered steps.
+- Include verification.
+- Include rollback or cleanup when relevant.
+- Keep conceptual explanation brief.
+- Link to reference and concept pages.
+
+## Reference
+
+Reference documentation provides exact facts.
+
+Good reference topics include API endpoints, GraphQL schema, CLI commands,
+environment variables, configuration, error codes, event schemas, package
+exports, permissions, cache keys, and feature flags.
+
+Rules:
+
+- Do not bury facts in prose.
+- Use tables, lists, and code blocks.
+- Include required vs optional status.
+- Include defaults, types, constraints, examples, and errors.
+- Include versioning and deprecation notes when known.
+- Avoid tutorials inside reference pages.
+
+## Explanation
+
+Explanation helps readers understand how and why the system works.
+
+Good explanation topics include architecture, data flow, rendering model,
+caching strategy, auth model, queueing model, consistency model, failure modes,
+tradeoffs, migration strategy, and design constraints.
+
+Rules:
+
+- Start with the problem or design pressure.
+- Explain the mental model.
+- Be honest about tradeoffs.
+- Include diagrams when helpful.
+- Link to ADRs or RFCs when available.
+- Do not turn explanation pages into step-by-step guides.
+- Do not hide operational instructions only in explanation pages.
+
+## Runbook
+
+A runbook is operational how-to plus reference. Use it when the reader needs to
+recover or safely operate a system.
+
+Rules:
+
+- Start with symptoms and impact.
+- Include first checks, dashboards, logs, metrics, or traces.
+- List likely causes and known false positives.
+- Provide mitigation steps and exact commands or links.
+- Include verification, rollback, and escalation.
+- Avoid long historical background before recovery steps.
+
+## Mixed Pages
+
+Some pages legitimately mix types. A landing page can include orientation,
+links, and a small quick start. A runbook can include reference tables and task
+steps. An API guide can include conceptual auth explanation plus endpoint
+reference links.
+
+The rule is not "never mix." The rule is to know the primary job of the page
+and keep everything else subordinate.
+
+## Smell Test
+
+| If the Reader Asks              | They Need    | Do Not Give Them            |
+| ------------------------------- | ------------ | --------------------------- |
+| I am new. Walk me through this. | Tutorial     | Full API reference          |
+| How do I do X?                  | How-to guide | Architecture essay          |
+| What does this option mean?     | Reference    | A blog post                 |
+| Why does this behave this way?  | Explanation  | A command list              |
+| Production is broken. What now? | Runbook      | Historical background first |

package/assets/skills/authoring-docs/references/principles.md

@@ -0,0 +1,98 @@
+---
+title: Documentation Principles
+description: Core principles for evidence-first technical documentation.
+---
+
+# Documentation Principles
+
+Documentation is part of the system. Maintain it with the same seriousness as
+code, tests, configuration, infrastructure, and runbooks.
+
+The goal is not to produce many pages. The goal is to reduce confusion, support
+safe change, and make the system legible to humans and agents.
+
+## Start With the Reader's Job
+
+Write from the reader's task, not the source tree.
+
+Weak:
+
+```md
+This service uses HTTP handlers, queues, and PostgreSQL.
+```
+
+Stronger:
+
+```md
+Use this service to publish content lifecycle events. The service accepts HTTP
+requests, persists event state in PostgreSQL, and processes asynchronous work
+through queue-backed workers.
+```
+
+Purpose comes first. Implementation details follow when they help the reader.
+
+## Task Completion Beats Encyclopedic Completeness
+
+Most readers arrive with a problem:
+
+- How do I run this locally?
+- How do I deploy this?
+- What does this flag do?
+- Why did this job fail?
+- What request shape should I send?
+- Can I safely change this config?
+
+Complete docs are useful only when structured around those moments.
+
+## Separate Documentation Modes
+
+Tutorials, how-to guides, reference pages, explanations, and runbooks do
+different jobs. Keep each page's primary job clear. Do not turn a first-run
+tutorial into a full reference manual, or a reference page into a long
+architecture essay.
+
+## Make Context Explicit for Agents
+
+Agents do not know which conventions are local, current, or tribal. Write down
+exact commands, paths, service names, environment names, runtime versions,
+configuration keys, ownership when known, constraints, non-goals, failure modes,
+and uncertainty.
+
+## Prefer Boring Consistency
+
+Across repositories, readers should know where to find setup, commands,
+configuration, API or CLI reference, deployment, observability, runbooks,
+architecture, and ownership. Familiar structure lowers cognitive load.
+
+## Lead With the Safe Path
+
+Document the common path first. Then explain variations, edge cases, production
+caveats, failure modes, unsafe commands, rollback, and compatibility
+boundaries.
+
+## Treat Reference as a Contract
+
+Reference docs for APIs, commands, configuration, events, packages, and
+environment variables should include names, types, required or optional status,
+defaults, allowed values, constraints, examples, errors, version notes, and
+deprecation notes when those facts exist.
+
+## Treat Operations Docs as Safety Equipment
+
+Runbooks are not background reading. They should help someone recover a system
+under pressure with symptoms, impact, likely causes, dashboards, logs, commands,
+verification, rollback, escalation, and known false positives.
+
+## Give Internal Docs the Same Quality Bar
+
+Internal docs can assume more context only when that context is linked or
+explained. They still need accurate examples, safe operations guidance, and
+clear ownership. Internal docs often guide production changes and future agent
+work.
+
+## Make Docs Age Visibly
+
+Docs get stale. Include version compatibility, last-verified dates for
+operational procedures, supported environments, deprecated behavior, ownership,
+source-of-truth links, and generated-reference markers when useful. Avoid
+claims like "new," "soon," or "temporary" without dates or issue links.