@doxbrix/doxloop 0.1.0

package/skills/doxloop-authoring/references/documentation-types.md

@@ -0,0 +1,236 @@
+# Documentation types and applicability
+
+Use this reference during discovery, planning, and review. Select documentation
+types from reader needs and source evidence. Do not create every type by default.
+After selecting the relevant types, use the matching expert type playbooks linked
+from `SKILL.md` for deeper investigation, structure, and senior quality gates.
+Apply audience flavor within the selected domain/type combination rather than
+treating audience as its own document template.
+
+## Contract for every page
+
+Give every page one identifiable reader job or reference purpose. Include:
+
+- an outcome-focused title and description;
+- the intended outcome in the opening;
+- prerequisites before the point where readers need them;
+- verified instructions, facts, or examples appropriate to the page type;
+- expected results and limitations where they affect completion;
+- recovery guidance only when supported by evidence;
+- a useful next step or related destination.
+
+Omit a section when it has no reader need. Do not add empty headings to satisfy
+a template.
+
+## Foundational pages
+
+### Overview
+
+Explain what the product is, who it serves, its primary outcomes, and how its
+major capabilities fit together.
+
+Use when the source exposes more than one reader-visible capability or when a
+new reader needs orientation before choosing a workflow.
+
+### Installation
+
+Cover supported installation methods, prerequisites, platform or runtime
+requirements, configuration needed before first use, and installation
+verification.
+
+Use when package metadata, build files, installers, or tests establish a
+supported installation path.
+
+### Quickstart
+
+Lead a new reader through the shortest verified path to a meaningful result.
+Show inputs, commands or code, expected output, and the next useful action.
+
+Use for every product that has an executable first-success workflow.
+
+## Learning and task pages
+
+### Tutorial
+
+Teach a complete workflow while introducing concepts in the order the reader
+needs them. Tutorials optimize for learning and confidence.
+
+Use when readers must combine multiple capabilities or understand a sequence
+before working independently.
+
+Keep the learning path controlled and reproducible. Deliver a meaningful
+working result, introduce concepts only when needed, and avoid optional branches
+that prevent the learner from knowing whether they succeeded.
+
+### How-to guide
+
+Help an informed reader complete one concrete task. State prerequisites, give
+ordered steps, show success, and include evidence-backed recovery guidance.
+
+Use for distinct, repeatable reader jobs supported by public interfaces or
+tests.
+
+Assume the reader is already oriented. Address one practical goal, allow
+relevant variation, and avoid turning the guide into a lesson or exhaustive
+reference.
+
+### Examples and recipes
+
+Provide small, verified solutions for common variants, integrations, or usage
+patterns without duplicating full guides.
+
+Use when tests, fixtures, or examples demonstrate multiple useful ways to apply
+the same interface.
+
+### User-interface workflow
+
+Guide readers through a stable visible workflow using exact labels, permissions,
+states, and outcomes. Use screenshots only when they materially reduce
+ambiguity, keep them current, and provide equivalent text instructions.
+
+Use when public UI source, routes, accessible labels, tests, or approved product
+captures establish the workflow.
+
+## Understanding pages
+
+### Concept
+
+Explain a mental model, lifecycle, relationship, or design constraint needed to
+use the product correctly. Connect the explanation to observable behavior.
+
+Use when readers must make decisions that procedures alone cannot answer.
+
+Explain the mental model, consequences, relationships, and tradeoffs. Connect
+each abstraction to reader-observable behavior and link to tasks or reference
+instead of embedding long procedures.
+
+### Architecture
+
+Explain reader-relevant components, boundaries, and data or control flow.
+
+Use only when the architecture is public, stable, and necessary for operators,
+integrators, or advanced users. Do not expose internal-only implementation.
+
+## Reference pages
+
+### API or SDK reference
+
+Document supported public endpoints, exports, parameters, return values,
+errors, authentication requirements, and verified examples.
+
+Use when routes, schemas, public types, generated specifications, or tests
+establish a supported programmatic interface.
+
+Define the reference scope and cover it consistently. Include types, required
+and optional values, defaults, return or response behavior, errors,
+authentication, limits, and verified examples when the interface supports them.
+
+In a Doxbrix project, use the native endpoint contract from
+`$doxloop-doxbrix`: one `<ApiEndpoint>` per HTTP operation with nested `<Param>`
+and `<Response>` children. Do not flatten endpoint reference into Markdown
+tables or generic request and response code blocks.
+
+### CLI reference
+
+Document commands, arguments, flags, defaults, exit behavior, and examples.
+
+Use when the product exposes a command-line interface.
+
+### Configuration reference
+
+Document supported keys, types, defaults, environment behavior, precedence,
+constraints, and examples.
+
+Use when configuration schemas, parsers, defaults, or tests provide evidence.
+
+### Data model
+
+Document public resources, fields, relationships, identifiers, lifecycle states,
+and invariants needed to use an API, SDK, or integration correctly.
+
+Use when schemas, public types, migrations, or contract tests establish a stable
+reader-visible model.
+
+### Events and webhooks
+
+Document event names, delivery and retry behavior, signatures, ordering,
+payloads, failure handling, and verified examples.
+
+Use when public event schemas, webhook routes, tests, or retry configuration
+provide evidence.
+
+## Operational and lifecycle pages
+
+### Authentication and security
+
+Explain supported authentication flows, permissions, credential handling, and
+security boundaries without exposing secrets or internal controls.
+
+Use when readers must authenticate, authorize, or make security-sensitive
+choices.
+
+### Deployment and operations
+
+Cover supported deployment, health verification, monitoring, backup, upgrade,
+and recovery workflows.
+
+Use for services or applications with evidence-backed operator responsibilities.
+
+### Troubleshooting
+
+Map observable symptoms to likely supported causes, diagnostics, and recovery
+steps.
+
+Use when errors, tests, or established behavior support reliable guidance.
+Never invent likely fixes.
+
+### Migration and upgrade
+
+Explain reader-visible changes, prerequisites, compatibility concerns, ordered
+steps, and verification.
+
+Use when the source contains versioned behavior, deprecations, migrations, or
+upgrade tooling.
+
+### Release notes and deprecations
+
+Summarize reader-visible additions, changes, fixes, removals, compatibility, and
+required actions for a defined release.
+
+Use when version history, release metadata, migrations, or deprecation markers
+provide verified evidence. Do not turn commit messages into unsupported product
+claims.
+
+### Support and compatibility
+
+State supported versions, platforms, runtimes, browsers, lifecycle status, and
+support boundaries.
+
+Use when package metadata, test matrices, release policy, or public
+configuration establishes these commitments.
+
+### Versioned documentation
+
+Maintain separate versions only when multiple product versions are actively
+supported and reader-visible behavior differs. Make the selected version clear,
+avoid mixing examples across versions, and link migrations between them.
+
+### Glossary
+
+Define domain terms only when several pages depend on the same non-obvious
+meaning. Prefer definitions near first use when a standalone glossary would not
+improve findability.
+
+## Prioritization
+
+Group proposed pages using:
+
+- **Must have**: required for the primary reader to understand, start, and
+  complete the product's main supported workflows.
+- **Next**: important for repeated use, broader capabilities, confident
+  decisions, or common recovery.
+- **Later**: valuable for advanced, less common, or lifecycle-specific needs.
+
+For every proposed page, name its reader, outcome, documentation type, and
+supporting source evidence. Omit a type when it has no distinct reader need or
+cannot be verified.

package/skills/doxloop-authoring/references/domain-ai-ml.md

@@ -0,0 +1,67 @@
+# AI and machine-learning expertise
+
+Use when readers configure, train, evaluate, deploy, or consume models, agents,
+embeddings, classifiers, generators, or other probabilistic systems.
+
+## Think like a senior AI product documentation lead
+
+Separate interface contract from probabilistic behavior. Document inputs,
+outputs, controls, limits, evaluation, observability, and human oversight. Make
+variability and failure visible without turning the guide into a research paper.
+
+## Investigate
+
+- model or capability identifiers, versions, availability, and lifecycle;
+- accepted input modalities, formats, sizes, preprocessing, and encoding;
+- output schema, streaming, termination, structured output, and validation;
+- configurable sampling, tools, retrieval, memory, context, and safety controls;
+- latency, quotas, token or usage accounting, batching, and concurrency when public;
+- determinism limits, seed behavior, confidence, abstention, and error handling;
+- evaluation fixtures, quality metrics, regression tests, and monitoring signals;
+- data handling, retention, training use, access controls, and deletion commitments;
+- prompt injection, unsafe content, tool authority, and human approval boundaries;
+- fallback, model migration, deprecation, and reproducibility evidence.
+
+## Design coverage
+
+Give readers a verified baseline example and an evaluation loop. Explain how to
+validate outputs before downstream use, bound tool permissions, handle malformed
+or unsafe results, monitor quality drift, and choose evidenced controls. Label
+sample output as illustrative when exact reproduction is not guaranteed.
+
+Keep model concepts connected to decisions: quality, latency, cost, context,
+safety, and operational complexity. Document structured schemas and observable
+errors precisely; describe subjective quality with evaluation methods rather
+than unsupported adjectives.
+
+## Navigation overlay
+
+Insert supported destinations into Getting started, Concepts, Guides, Reference,
+and Operations:
+
+```text
+Models and capabilities
+Inputs, prompting, and context
+Tools, retrieval, and structured output
+Evaluation and quality
+Safety and human oversight
+Limits, latency, and usage
+Monitoring and fallback
+Model versions and migration
+```
+
+Put evaluation and output validation near the first real workflow, not only in
+advanced operations.
+
+## Never assume
+
+Do not claim accuracy, fairness, safety, determinism, privacy, data residency,
+training-data exclusion, model identity, context size, retention, or regulatory
+fitness without authoritative evidence. Never present generated output as a
+guaranteed response or recommend unreviewed automation for consequential actions.
+
+## Senior quality gate
+
+A reader must be able to run the supported capability, validate its output,
+understand material variability and limits, constrain authority, evaluate changes,
+and operate a safe fallback for evidenced failure modes.

package/skills/doxloop-authoring/references/domain-api-platform.md

@@ -0,0 +1,68 @@
+# API platform expertise
+
+Use when a public API is the product or a primary integration surface. Combine
+with a more specific business domain when the API represents payments,
+commerce, identity, data, or infrastructure.
+
+## Think like a senior API documentation lead
+
+Document the integration lifecycle, not only endpoints: obtain access, select an
+environment, form a valid request, identify resources, handle asynchronous
+state, recover from failure, test safely, observe production behavior, and
+upgrade without contract surprises.
+
+## Investigate
+
+- base URLs, environments, media types, version negotiation, and transport;
+- authentication methods, credential scopes, rotation, and test credentials;
+- resource identifiers, ownership, lifecycle states, and concurrency behavior;
+- request headers, validation, defaults, pagination, filtering, sorting, and search;
+- response envelopes, nullability, timestamps, money, units, and unknown fields;
+- error schema, status mapping, retryability, idempotency, and correlation IDs;
+- synchronous versus asynchronous operations, polling, events, and webhooks;
+- rate or usage limits, quotas, batching, caching, and timeout behavior;
+- compatibility, deprecation, changelog, SDK, and specification sources.
+
+## Design coverage
+
+Give developers a verified first call before exhaustive reference. Use concepts
+to explain authentication, resource relationships, state transitions, delivery
+semantics, and error strategy. Keep task guides for multi-operation outcomes and
+reference pages for lookup. Use one consistent endpoint contract across the
+declared public surface.
+
+Examples must use safe placeholders, show the complete required request, include
+an expected response or observable result, and demonstrate error handling where
+production correctness depends on it. Prefer the product's canonical language
+or protocol examples; do not manufacture SDKs.
+
+## Navigation overlay
+
+Insert supported destinations into Developer portal, Guides, Concepts, and
+Reference:
+
+```text
+Environments and authentication
+Resources and lifecycle
+Common integration workflows
+Pagination, idempotency, and concurrency
+Events and webhooks
+Errors and limits
+Testing and production readiness
+Versioning and deprecations
+```
+
+Keep exact operations in API reference and multi-operation outcomes in Guides.
+
+## Never assume
+
+Do not invent rate limits, retry rules, idempotency guarantees, ordering,
+exactly-once delivery, field stability, authentication scopes, sandbox parity,
+version lifetime, or backward compatibility. An OpenAPI file is strong contract
+evidence but may not prove operational limits or delivery semantics.
+
+## Senior quality gate
+
+A developer must be able to make a valid first request, understand the core
+resource model, implement supported failure handling, and locate every contract
+element promised by the reference scope without reverse-engineering examples.

package/skills/doxloop-authoring/references/domain-cli-tool.md

@@ -0,0 +1,65 @@
+# CLI tool expertise
+
+Use when readers operate or automate a product through commands, subcommands,
+arguments, flags, standard streams, or process exit status.
+
+## Think like a senior CLI documentation maintainer
+
+Treat interactive use, scripts, and CI as distinct contexts. A command contract
+includes invocation syntax, input sources, precedence, output destination and
+format, prompts, side effects, exit behavior, and cleanup—not just a flag list.
+
+## Investigate
+
+- installation, executable names, shells, platforms, and runtime prerequisites;
+- command hierarchy, aliases, positional arguments, required and repeatable options;
+- defaults, environment variables, config files, and precedence rules;
+- stdin, stdout, stderr, TTY detection, colors, prompts, and non-interactive mode;
+- text and machine-readable output schemas and stability commitments;
+- exit status, partial success, retries, cancellation, signals, and cleanup;
+- filesystem effects, overwrite behavior, idempotency, dry-run, and confirmation;
+- authentication, credential lookup, context/profile selection, and redaction;
+- completion, help, diagnostics, compatibility, and deprecation behavior.
+
+## Design coverage
+
+Provide installation and a verified first command. Organize task guides around
+outcomes and reference around the command tree. For every command, document
+syntax, purpose, arguments, options, defaults, input, output, side effects, exit
+behavior, examples, and consequential limitations when supported.
+
+Examples for automation must avoid prompts, show quoting safely, distinguish
+stdout from stderr when relevant, and check exit status or structured output.
+Use the product's real help output as evidence but rewrite it into reader-focused
+documentation rather than dumping it unchanged.
+
+## Navigation overlay
+
+Insert supported destinations into Getting started, Guides, and Command
+reference:
+
+```text
+Installation and authentication
+Common workflows
+Configuration and precedence
+Command hierarchy
+Input, output, and exit status
+Automation and non-interactive use
+Diagnostics and troubleshooting
+Upgrade and release notes
+```
+
+Keep task sequences separate from exhaustive command lookup.
+
+## Never assume
+
+Do not infer option precedence, shell portability, overwrite safety, atomicity,
+stable JSON, exit codes, retry behavior, or non-interactive suitability from an
+option name. Never show secrets directly on command lines when a safer supported
+input exists.
+
+## Senior quality gate
+
+A reader must be able to install the executable, complete the primary task both
+interactively and in supported automation, predict side effects and output, and
+handle documented failure through exit status or diagnostics.

package/skills/doxloop-authoring/references/domain-data-platform.md

@@ -0,0 +1,65 @@
+# Data-platform expertise
+
+Use when the product ingests, stores, transforms, queries, serves, governs, or
+observes data through connectors, pipelines, warehouses, lakes, catalogs, or BI.
+
+## Think like a senior data-platform documentation architect
+
+Trace data from source to consumer. For each stage, identify ownership, schema,
+freshness, quality, state, failure, replay, and observability. Separate control
+plane configuration from data plane movement when the product exposes both.
+
+## Investigate
+
+- connectors, credentials, network prerequisites, source and destination support;
+- datasets, namespaces, schemas, types, identifiers, and evolution behavior;
+- full, incremental, CDC, batch, streaming, checkpoint, and watermark semantics;
+- transformation ordering, dependencies, materialization, and execution state;
+- scheduling, concurrency, retries, backfill, replay, and partial-failure handling;
+- quality checks, freshness, lineage, metadata, ownership, and alerting;
+- query behavior, partitioning, limits, caching, exports, and downstream contracts;
+- access control, secrets, sensitive data, retention, deletion, and audit evidence;
+- environment promotion, versioning, compatibility, cost or usage signals.
+
+## Design coverage
+
+Start with one bounded source-to-result path and show how to verify records,
+schema, and freshness. Use concepts for execution state, incremental behavior,
+schema evolution, lineage, and failure domains. Give operators runbooks for
+stalled, late, rejected, duplicated, or incomplete data only when diagnostics
+and recovery are evidenced.
+
+Document who owns schema changes and how downstream compatibility is checked.
+Make destructive reprocessing, replacement, truncation, or backfill behavior
+explicit before steps that can duplicate or lose data.
+
+## Navigation overlay
+
+Insert supported destinations following data flow:
+
+```text
+Connectors and credentials
+Datasets, schemas, and types
+Pipelines and execution
+Transformations and dependencies
+Incremental processing and backfill
+Data quality, freshness, and lineage
+Query and delivery
+Monitoring and recovery
+```
+
+Order navigation from source to consumer; keep control-plane configuration and
+data-plane behavior distinct when readers operate them differently.
+
+## Never assume
+
+Do not infer exactly-once delivery, ordering, transactional boundaries, zero
+data loss, freshness, automatic schema compatibility, encryption, retention,
+lineage completeness, or recovery guarantees. A successful job status does not
+necessarily prove complete or correct data unless the product defines it so.
+
+## Senior quality gate
+
+A reader must be able to configure a supported flow, validate data correctness
+and freshness, understand schema and execution semantics, diagnose evidenced
+failure states, and recover without accidental duplication or loss.

package/skills/doxloop-authoring/references/domain-developer-library.md

@@ -0,0 +1,63 @@
+# Developer library expertise
+
+Use for reusable packages, frameworks, modules, or SDKs consumed from application
+code.
+
+## Think like a senior library documentation maintainer
+
+Teach the smallest correct mental model: how the package is installed, imported,
+initialized, called, composed, configured, observed, and upgraded. Distinguish
+the stable public API from implementation exports and generated internals.
+
+## Investigate
+
+- package metadata, supported runtimes, module formats, peer dependencies, and engines;
+- documented entry points, exports maps, public types, generics, and overloads;
+- initialization, configuration, defaults, lifecycle, cleanup, and concurrency;
+- sync or async behavior, cancellation, streaming, retries, and error types;
+- mutability, nullability, ownership, resource use, and thread or process safety;
+- framework adapters, plugins, extension points, and compatibility matrices;
+- tests and fixtures showing canonical use, edge cases, and failure contracts;
+- deprecations, replacement APIs, versioning, and migration evidence.
+
+## Design coverage
+
+Start with a complete minimal program that uses the supported public entry point.
+Explain the central abstraction before presenting variants. Organize guides by
+developer outcome and reference by the library's public namespace. Show types
+when they reduce ambiguity; explain runtime behavior that types cannot express.
+
+Examples must compile or be traceable to contract tests. Include imports,
+initialization, cleanup, and error handling needed for correctness. Do not make
+snippets deceptively short by hiding essential setup.
+
+## Navigation overlay
+
+Insert supported destinations into Getting started, Guides, Concepts, and
+Reference:
+
+```text
+Installation and compatibility
+Initialization and configuration
+Core abstractions and lifecycle
+Common usage patterns
+Framework adapters and extension points
+Public API reference
+Errors and debugging
+Upgrades and deprecations
+```
+
+Organize reference by the stable public namespace, never by source folders.
+
+## Never assume
+
+Do not document every exported symbol as supported. Do not infer browser,
+runtime, framework, thread-safety, performance, serialization, or semantic
+versioning guarantees without evidence. Do not describe internal classes merely
+because they are reachable in source.
+
+## Senior quality gate
+
+A developer must be able to choose the correct entry point, run the first
+example, understand object or function lifecycle, handle documented failures,
+and locate consistent reference for the declared public surface.

package/skills/doxloop-authoring/references/domain-ecommerce.md

@@ -0,0 +1,63 @@
+# E-commerce expertise
+
+Use when the product manages catalog, pricing, carts, checkout, orders,
+inventory, fulfillment, returns, or commerce integrations.
+
+## Think like a senior commerce documentation lead
+
+Model the customer journey and the operational order lifecycle separately, then
+show where they meet. Make scope explicit across store, channel, market,
+location, customer, and order. Treat price, availability, payment, tax,
+fulfillment, and returns as related but independently verified concerns.
+
+## Investigate
+
+- products, variants, collections, attributes, media, publication, and identifiers;
+- price lists, currencies, discounts, promotions, tax inputs, and rounding;
+- inventory source, reservation, allocation, availability, and oversell behavior;
+- cart and checkout lifecycle, customer identity, address, shipping, and payment handoff;
+- order states, edits, cancellation, fulfillment, tracking, return, exchange, and refund;
+- channels, stores, locales, markets, warehouses, and configuration scope;
+- import/export, synchronization, events, webhooks, and external system ownership;
+- permissions, personally identifiable data, retention, and safe test fixtures.
+
+## Design coverage
+
+Use lifecycle-oriented concepts for catalog publication and orders. Give
+merchants and operators task guides for daily work; give integrators contract
+guidance for synchronization, identifiers, state mapping, and recovery. State
+which system is authoritative for each shared object when evidence establishes it.
+
+Use realistic but fictional products, customers, addresses, and amounts. Explain
+how readers verify availability, totals, order state, and fulfillment outcomes.
+
+## Navigation overlay
+
+Insert supported destinations by the commerce lifecycle:
+
+```text
+Catalog and publication
+Pricing, discounts, and tax inputs
+Inventory and availability
+Cart and checkout
+Orders and order changes
+Fulfillment and tracking
+Returns, exchanges, and refunds
+Channels, markets, and integrations
+```
+
+Keep merchant operations separate from customer tasks and integration contracts.
+
+## Never assume
+
+Do not invent tax calculation, discount stacking, inventory consistency,
+reservation duration, payment behavior, return eligibility, refund timing,
+shipping promises, marketplace ownership, or privacy compliance. A visible UI
+label does not prove the underlying accounting or fulfillment semantics.
+
+## Senior quality gate
+
+Readers must be able to predict how a supported catalog change becomes visible,
+how an order moves through evidenced states, which actor owns each operational
+step, and how to diagnose mismatches without creating duplicate orders or
+incorrect inventory.