@doxbrix/doxloop 0.1.0

package/skills/doxloop-authoring/references/type-developer-portal.md

@@ -0,0 +1,69 @@
+# Developer-portal playbook
+
+Use when developers need an integrated documentation experience spanning
+onboarding, concepts, implementation tasks, contract reference, and production
+operation of an API, SDK, extension platform, or developer tool.
+
+## Architect the journey
+
+Organize around developer maturity:
+
+1. evaluate fit and prerequisites;
+2. obtain access and reach first success;
+3. understand the minimum domain and resource model;
+4. complete common end-to-end integrations;
+5. look up exact contracts;
+6. test, debug, secure, observe, and ship;
+7. maintain compatibility and migrate.
+
+Do not make the landing page a feature inventory. Route readers by their next
+job. Keep task guides outcome-based and reference exhaustive within its declared
+scope. Cross-link concepts at the decision point rather than duplicating them.
+
+## Expected coverage
+
+Select evidence-backed modules for environments, credentials, first request or
+program, core resources, common workflows, errors, limits, events, test strategy,
+security, observability, compatibility, changelog, and support. Include SDK or
+CLI material only when those surfaces are supported.
+
+Use consistent examples, identifiers, fictional data, and terminology across
+the portal. Evolve a small canonical scenario from quickstart through advanced
+guides so readers can transfer understanding without copying one oversized sample.
+
+## Production-readiness lens
+
+Where supported, cover credential lifecycle, retries, idempotency, timeouts,
+concurrency, pagination, asynchronous state, logging and correlation, sandbox
+differences, versioning, and safe failure. Do not label an integration
+production-ready when these concerns are unknown.
+
+## Standard navigation
+
+Promote substantial API, SDK, or changelog surfaces to top navigation. Use this
+left-navigation order:
+
+```text
+Overview
+Getting started
+Core concepts
+Developer guides
+SDKs
+API reference
+Events and webhooks
+Errors and limits
+Testing
+Production readiness
+Troubleshooting
+Migration guides
+Changelog
+```
+
+Omit unsupported surfaces and merge SDKs or API reference into a single
+Reference group when they are small.
+
+## Senior quality gate
+
+A developer can assess fit, reach first success, build the primary supported
+integration, locate a consistent contract, and prepare for evidenced production
+failure and change without reverse-engineering the source.

package/skills/doxloop-authoring/references/type-getting-started.md

@@ -0,0 +1,59 @@
+# Getting-started playbook
+
+Use when a reader needs a controlled path from a clean state to first meaningful
+value. This playbook can produce an installation page, quickstart, or short
+onboarding sequence depending on complexity.
+
+## Define first success
+
+Choose an outcome that proves the product is working for the primary reader—not
+merely that files were installed or a process started. Bound the path to one
+supported environment and the minimum required decisions. Move optional branches
+after success.
+
+## Build the path
+
+1. State the result and expected time or effort only when evidenced.
+2. List supported prerequisites and required access.
+3. Install or connect using the canonical supported method.
+4. Configure only values needed for this path, using safe placeholders.
+5. Perform the smallest complete workflow.
+6. Show the observable success result.
+7. Give recovery for evidenced common failures.
+8. Link to the next task, concept, and reference needed for real use.
+
+Explain each new concept only at the moment it becomes necessary. Keep commands
+and code complete enough to run. When setup differs materially by platform,
+runtime, role, or deployment model, choose a declared primary path and link to
+verified alternatives rather than interleaving every branch.
+
+## Evidence and verification
+
+Trace prerequisites to package or platform metadata, steps to public interfaces,
+and expected results to tests, fixtures, or safe execution. Test from a clean or
+representative state when feasible. Do not call a path quick if it omits required
+security, cleanup, or initialization.
+
+## Standard navigation
+
+Contribute this block under Documentation:
+
+```text
+Getting started
+  Overview
+  Prerequisites
+  Installation or access
+  Initial configuration
+  Quickstart
+  Verify the result
+  Next steps
+```
+
+For a compact site, keep Overview at the site root and flatten the remaining
+pages when the group would contain fewer than two useful destinations.
+
+## Senior quality gate
+
+A qualified new reader can follow the path without hidden knowledge, recognize
+success, recover from supported setup failures, and understand where to go next.
+The path leaves no unsafe credential, sample data, or process state unexplained.

package/skills/doxloop-authoring/references/type-integration-guide.md

@@ -0,0 +1,59 @@
+# Integration-guide playbook
+
+Use for a bounded connection between the documented product and another named
+system, protocol, platform, or workflow.
+
+## Define the integration contract
+
+Identify both systems, supported versions, direction of control and data,
+prerequisites, authentication on each side, object mapping, trigger, delivery
+semantics, ownership, and completion. State which system is authoritative for
+each shared field or state when evidence supports it.
+
+## Build the guide
+
+1. Explain supported outcome, topology, and limitations.
+2. List access, versions, network, credentials, and test-data prerequisites.
+3. Configure the provider side and verify access.
+4. Configure the consumer side and verify the connection.
+5. Map identifiers, fields, states, or events explicitly.
+6. Run one safe end-to-end test.
+7. Verify results in both systems.
+8. Cover retries, duplicates, partial failure, monitoring, and disablement when supported.
+
+Use a mapping table only when several exact fields or states require comparison.
+Keep provider-specific terminology distinct from product terminology. Show
+secret-handling boundaries without exposing credential values.
+
+## Operational ownership
+
+Document who rotates credentials, responds to failure, replays or reconciles
+data, upgrades either side, and collects escalation evidence when public behavior
+defines those responsibilities. State sandbox or test-environment differences.
+
+## Standard navigation
+
+Promote `Integrations` when the product maintains several integrations. For one
+integration, contribute this block under Guides or Integrations:
+
+```text
+Integration overview
+Prerequisites
+How the integration works
+Configure the integration
+Data and object mapping
+Integration workflows
+Test the integration
+Operate the integration
+Maintain or remove it
+Troubleshooting
+```
+
+For an integration catalog, repeat the bounded block per provider while sharing
+common authentication, event, and troubleshooting concepts where identical.
+
+## Senior quality gate
+
+A qualified integrator can establish the connection, prove end-to-end behavior,
+understand mapping and ownership, detect failure, and disable or recover the
+integration without duplicates, silent loss, or unsupported assumptions.

package/skills/doxloop-authoring/references/type-migration-release.md

@@ -0,0 +1,66 @@
+# Migration-and-release playbook
+
+Use when readers must understand a defined release or move safely between
+versions, interfaces, schemas, configurations, or deployment models.
+
+## Build from a verified change inventory
+
+Classify reader-visible changes as added, changed, fixed, deprecated, removed,
+security-relevant, or operational. For each change, identify affected readers,
+old behavior, new behavior, required action, compatibility, timing, and evidence.
+Do not convert commit messages directly into release claims.
+
+## Migration procedure
+
+Include:
+
+- supported source and target versions;
+- who must migrate and who is unaffected;
+- prerequisites, backups, permissions, capacity, and downtime when evidenced;
+- deprecated or removed behavior and supported replacement;
+- ordered code, data, configuration, or operational changes;
+- compatibility window and mixed-version behavior when supported;
+- verification of behavior and data after migration;
+- rollback or roll-forward conditions supported by the product;
+- cleanup and next-version considerations.
+
+Separate upgrade mechanics from application or integration changes when
+different owners perform them. Give reusable transformations or mapping tables
+for repeated renamed fields, flags, endpoints, or states.
+
+## Release notes
+
+Lead with reader impact and action. Group changes consistently; link to updated
+guidance; distinguish breaking changes from new optional capability; and avoid
+internal implementation detail, issue-list dumps, and marketing language.
+
+## Standard navigation
+
+Promote `Release notes` when maintained. Keep actionable migration ahead of
+chronology:
+
+```text
+Release overview
+Supported versions
+What's new
+Breaking changes
+Migration guides
+  Choose a path
+  Prepare
+  Migrate
+  Verify
+  Roll back or roll forward
+Deprecations
+Compatibility
+Release notes
+  Versions, newest first
+```
+
+For versioned sites, link each source version directly to its supported target
+migration instead of making readers infer a multi-hop path.
+
+## Senior quality gate
+
+An affected reader can determine whether action is required, execute the change
+in the correct order, verify compatibility and outcome, and recover using only
+supported paths. Unaffected readers are not alarmed by ambiguous scope.

package/skills/doxloop-authoring/references/type-sdk-guide.md

@@ -0,0 +1,63 @@
+# SDK-guide playbook
+
+Use when a supported language SDK or client library needs onboarding, idiomatic
+task guidance, and public-symbol reference.
+
+## Design for the language ecosystem
+
+Follow the package manager, import style, naming, async model, error conventions,
+resource management, and code-formatting norms evidenced by the SDK. Do not
+transliterate examples mechanically between languages; verify each SDK surface.
+
+## Expected coverage
+
+- supported language and runtime versions;
+- installation and version selection;
+- client construction, configuration, authentication, and cleanup;
+- a complete first call and expected typed result;
+- core resource or service groupings;
+- common workflows with idiomatic examples;
+- pagination, streaming, async, cancellation, retries, and timeouts when supported;
+- exception or result-error hierarchy and recovery;
+- test doubles, sandbox use, logging, and debugging when public;
+- public classes, functions, methods, properties, types, defaults, and deprecations;
+- upgrade and compatibility guidance.
+
+Explain server behavior in shared concepts and SDK behavior in language-specific
+guides. Keep cross-language examples semantically aligned without hiding real
+differences.
+
+## Example discipline
+
+Compile or execute examples when safe. Include imports, credential placeholders,
+initialization, awaited operations, disposal, and error handling required for
+correctness. Use one coherent sample domain and avoid global mutable state unless
+the supported API requires it.
+
+## Standard navigation
+
+Promote `SDKs` when several maintained language SDKs exist. Use this block:
+
+```text
+SDK overview
+Getting started
+  Install the SDK
+  Configure credentials
+  Initialize the client
+  Make the first call
+SDK guides
+Language SDKs
+SDK reference
+Testing and debugging
+Compatibility and upgrades
+Release notes
+```
+
+Create a separate language subtree only when its lifecycle or behavior differs
+materially; otherwise keep shared concepts outside language-specific reference.
+
+## Senior quality gate
+
+A developer can install the correct version, initialize the client safely, use
+idiomatic types and lifecycle, handle supported failures, and locate the stable
+public SDK surface without consulting implementation code.

package/skills/doxloop-authoring/references/type-troubleshooting-kb.md

@@ -0,0 +1,63 @@
+# Troubleshooting knowledge-base playbook
+
+Use when source evidence supports reliable diagnosis from observable symptoms.
+Do not create speculative fix lists.
+
+## Write from symptom to resolution
+
+Title each article with the observable symptom or failed outcome. Start with the
+scope and safety impact, then use this sequence:
+
+1. confirm the symptom and affected scope;
+2. collect the least invasive diagnostic evidence;
+3. check likely causes in a discriminating order;
+4. apply one supported recovery at a time;
+5. verify restoration of the original outcome;
+6. collect escalation evidence when recovery fails.
+
+Use decision tables or branches only when a signal clearly distinguishes the
+next action. Put destructive, security-sensitive, or data-changing recovery
+behind prerequisites, warnings, backup, and explicit target checks.
+
+## Evidence sources
+
+Prefer documented errors, public diagnostics, contract tests, support fixtures,
+health endpoints, logs, exit behavior, and reproducible failure tests. Error text
+alone may be unstable; pair it with an error code, state, or reader-observable
+condition when available.
+
+## Avoid weak articles
+
+Do not tell readers to retry, restart, reinstall, clear caches, delete state,
+disable security, or contact support unless evidence establishes when and why.
+Do not list many plausible causes without a way to distinguish them. Never ask
+readers to publish secrets or personal data in diagnostic output.
+
+## Standard navigation
+
+Promote `Troubleshooting` only when the knowledge base is a major destination.
+Organize the left navigation by observable symptom family:
+
+```text
+Troubleshooting overview
+Collect diagnostics
+Installation problems
+Authentication and access problems
+Configuration problems
+Connectivity problems
+Workflow problems
+Integration problems
+Performance or capacity problems
+Error reference
+Recovery
+Get support
+```
+
+Omit unsupported families. Put individual articles under the symptom a reader
+would recognize, not the internal component suspected of causing it.
+
+## Senior quality gate
+
+The article lets a reader recognize that it applies, diagnose safely, choose a
+supported recovery based on evidence, verify success, and escalate with useful
+redacted information when the issue remains.

package/skills/doxloop-authoring/references/type-user-guide.md

@@ -0,0 +1,59 @@
+# User-guide playbook
+
+Use for recurring end-user workflows through a UI or other user-facing control
+surface. Pair with an administrator guide when shared configuration and daily
+work have different owners.
+
+## Build around user jobs
+
+Identify the user's start state, goal, required access, primary objects, and
+observable completion. Organize navigation by recognizable tasks and lifecycle,
+not by internal service or screen implementation. Give each page one primary job.
+
+## Procedure contract
+
+For each workflow:
+
+1. state what the reader will accomplish;
+2. state role, prerequisites, and required starting state;
+3. use exact visible labels and ordered actions;
+4. explain consequential choices before the action;
+5. show the resulting visible state;
+6. provide evidence-backed recovery or reversal;
+7. link to the next likely job.
+
+Use screenshots for orientation, dense configuration, or state confirmation when
+they materially reduce ambiguity. Keep text complete without the image. Account
+for empty, loading, permission-denied, validation, and completed states supported
+by evidence.
+
+## Findability and support
+
+Use user vocabulary, stable object names, and symptom language. Keep conceptual
+explanations short and connected to decisions. Link administrators to settings
+they own rather than instructing an end user to perform unauthorized actions.
+
+## Standard navigation
+
+Use `Help center` or `Documentation` as the primary top-navigation label. Use
+this left-navigation block:
+
+```text
+Welcome
+Get started
+Common tasks
+Manage your work
+Collaboration
+Personal settings
+Troubleshooting
+What's new
+```
+
+Replace generic task groups with product vocabulary and order them by frequency
+and lifecycle. Keep organization-wide settings in an administrator journey.
+
+## Senior quality gate
+
+A qualified user can find the task by goal, complete it using current labels,
+recognize success, understand the effect of consequential choices, and recover
+or escalate without guessing or requiring an image.

package/skills/doxloop-doxbrix/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: doxloop-doxbrix
+description: Author and maintain documentation in native Doxbrix format, including the versioned spaces-and-navigation docs.json manifest, application-derived colors, fonts, and logos, MDX page frontmatter, rich components, and interactive API reference pages built with ApiEndpoint, Param, and Response. Use with doxloop-authoring whenever .doxloop/project.json selects the doxbrix generator, when creating or editing Doxbrix pages, API endpoint reference, or themes, or when reviewing Doxbrix presentation, component, and navigation correctness.
+---
+
+# Doxloop Doxbrix Format
+
+Produce documentation that renders natively in Doxbrix. Use this skill together
+with `$doxloop-authoring`; that skill owns discovery, consultation, coverage, and
+writing quality.
+
+## Read before editing
+
+1. Read `.doxloop/project.json` and confirm `generator` is `doxbrix` or absent.
+2. Read [references/manifest.md](references/manifest.md).
+3. Read [references/components.md](references/components.md) before authoring
+   rich layouts.
+4. Inspect existing `docs.json` and pages for established theme, terminology,
+   paths, and component patterns.
+
+When creating or changing HTTP API reference, also read
+[references/api-endpoints.md](references/api-endpoints.md) and follow its
+contract exactly.
+
+If the generator is not `doxbrix`, stop and use its installed Doxloop format
+skill instead.
+
+## Author native Doxbrix content
+
+- Write `.mdx` when using Doxbrix components.
+- Include `title` and an outcome-focused `description` in frontmatter.
+- Use standard Markdown for ordinary prose.
+- Use a rich component only when it communicates the content more clearly.
+- Use `<Steps>` for sequential procedures, `<CodeGroup>` for alternative
+  commands, `<Accordion>` for compact FAQs, and `<CardGroup>` for purposeful
+  navigation.
+- Use the six Doxbrix callout types accurately: `<Info>`, `<Note>`, `<Tip>`,
+  `<Check>`, `<Warning>`, and `<Danger>`.
+- Use one native `<ApiEndpoint>` block per HTTP operation, with a `<Param>` for
+  every verified parameter and a `<Response>` for every documented status.
+  Never replace the native endpoint block with Markdown tables or standalone
+  request and response code fences.
+- Keep component tags balanced and put nested block content on separate lines.
+- Use root-relative page links that match manifest page files.
+
+Do not emit Docusaurus directives such as `:::tip`, Docusaurus theme imports, or
+`sidebars.js` entries in a Doxbrix project.
+
+## Maintain navigation
+
+Implement the semantic top/left navigation plan composed by
+`$doxloop-authoring`. Map major reader surfaces to Doxbrix spaces or supported
+site links and map left-navigation groups to nested `docs.json` nodes. Preserve
+the planned labels, order, hierarchy, and routes unless Doxbrix requires a
+documented adaptation; do not copy empty template groups.
+
+Treat `docs/docs.json` as the canonical manifest for new Doxloop projects.
+Legacy projects may keep `docs.json` at the project root. Add every
+reader-facing page exactly once under a relevant space and navigation group.
+Assign meaningful named icons to spaces and primary group, page, link, and API
+nodes. Choose icons by reader meaning, keep the vocabulary consistent, and
+preserve visible text labels; icons supplement labels rather than replace them.
+Preserve supported link, label, divider, and API nodes.
+
+## Apply captured branding
+
+Use the identity and any confirmed external design profile gathered through
+`$doxloop-authoring` and [references/manifest.md](references/manifest.md):
+
+- write colors, mode, fonts, logos, favicon, and backgrounds under `theme`;
+- copy public logos and licensed local font files into the documentation content
+  directory and use root-relative paths;
+- provide separate light and dark assets when the application does;
+- preserve readable contrast and use fallbacks for fonts that cannot be copied.
+
+Do not invent missing brand values or reference files outside the documentation
+project.
+
+## Verify
+
+Run `doxloop test` and `doxloop preview --open`. Confirm rich blocks, navigation,
+page title, description, code highlighting, and responsive layout render in the
+Doxbrix preview.

package/skills/doxloop-doxbrix/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Doxloop Doxbrix Format"
+  short_description: "Author native Doxbrix docs, API endpoints, and components"
+  default_prompt: "Use $doxloop-doxbrix to author documentation in native Doxbrix MDX and navigation format, using ApiEndpoint with Param and Response for HTTP API reference."

package/skills/doxloop-doxbrix/references/api-endpoints.md

@@ -0,0 +1,128 @@
+# Doxbrix API endpoint reference
+
+Use this contract for every HTTP operation documented in a Doxbrix project.
+The native reader turns this structure into the method/path bar, Try it action,
+grouped parameters, generated request example, and response tabs.
+
+- [Page contract](#page-contract)
+- [Canonical syntax](#canonical-syntax)
+- [Verification](#verification)
+
+## Page contract
+
+- Prefer one endpoint page and one `<ApiEndpoint>` block per operation.
+- Use the page title for the operation name, such as `List projects`.
+- Open with one short sentence describing the observable behavior.
+- Put `method`, `path`, `baseUrl`, `summary`, and `description` on
+  `<ApiEndpoint>`.
+- Add one `<Param>` for every verified path, query, header, or body parameter.
+- Add one `<Response>` for the successful status and each important verified
+  error status.
+- Keep example values realistic but visibly non-secret.
+- Use raw JSON inside `<Response>` without an additional fenced code block.
+- Get every name, type, required flag, default, limit, status, and example shape
+  from OpenAPI, public schemas, route contracts, or tests. Invent nothing.
+
+## Canonical syntax
+
+```mdx
+---
+title: List projects
+description: List the projects available to the current API key.
+---
+
+Lists the projects in your workspace that the API key can access.
+Results use cursor pagination.
+
+<ApiEndpoint
+  method="GET"
+  path="/projects"
+  baseUrl="https://api.example.com/v1"
+  summary="List projects"
+  description="Returns a page of projects."
+>
+<Param
+  name="Authorization"
+  in="header"
+  type="string"
+  required
+  example="Bearer api_test_example"
+>
+Bearer token sent in the `Authorization` header.
+</Param>
+<Param
+  name="limit"
+  in="query"
+  type="integer"
+  example="50"
+>
+Maximum results per page. Defaults to 50; maximum 100.
+</Param>
+<Param
+  name="cursor"
+  in="query"
+  type="string"
+  example="next_page_cursor"
+>
+Pagination cursor returned by the previous response.
+</Param>
+<Response
+  status={200}
+  contentType="application/json"
+  description="Projects listed"
+>
+{
+  "data": [
+    {
+      "id": "prj_01H9",
+      "name": "Acme Docs"
+    }
+  ],
+  "nextCursor": null
+}
+</Response>
+<Response
+  status={401}
+  contentType="application/json"
+  description="Authentication failed"
+>
+{
+  "error": {
+    "code": "unauthorized",
+    "message": "Provide a valid API key."
+  }
+}
+</Response>
+</ApiEndpoint>
+```
+
+Use only supported values:
+
+- `method`: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`;
+- `in`: `path`, `query`, `header`, or `body`;
+- `required`: prefer a bare boolean attribute when true; `{true}` is also
+  accepted; omit it when false;
+- `status`: a numeric expression such as `{200}`;
+- `contentType`: normally `application/json`, when verified.
+
+For every `{placeholder}` in `path`, add a matching required path parameter:
+
+```mdx
+<Param name="projectId" in="path" type="string" required example="prj_01H9">
+Project identifier.
+</Param>
+```
+
+Do not use a Markdown parameter table, a prose-only endpoint, or separate cURL
+and response fences in place of `<ApiEndpoint>`. The reader generates the
+request presentation from the block attributes and parameter examples.
+
+## Verification
+
+Run `doxloop test`, then inspect the page in `doxloop preview --open`. Confirm:
+
+- the method and path appear in the endpoint bar;
+- header, path, and query parameters appear in their proper sections;
+- required and type badges are correct;
+- the request example uses the verified base URL and parameter examples;
+- success and error statuses appear as response tabs with valid example bodies.