@doxbrix/doxloop 0.1.4 → 0.2.0

package/skills/doxloop-authoring/references/screenshots.md

@@ -1,213 +1,152 @@
 # Application guide screenshots
 
-Use this workflow only for screenshots of the product being documented. The
-existing `doxloop capture` command inspects external documentation design
-references and is not part of this workflow.
-
-## Decide whether capture is enabled
-
-Capture application screenshots when any of these conditions applies:
-
-- the task prompt says screenshots are required because `--screenshots` was
-  supplied;
-- the user explicitly asks to include, create, capture, or refresh screenshots;
-- `.doxloop/project.json` sets `application.screenshots.policy` to `auto` and
-  the agreed page is a visible user-interface workflow.
-
-Do not capture when the task prompt disables screenshots; when the project
-policy is `off` and the task prompt does not explicitly require them; when the
-request mentions screenshots only negatively or as an example; or when the page
-has no meaningful visible application state. An explicit `--screenshots`
-requirement overrides project policy for that run. Never add screenshots to API
-or CLI procedures merely for decoration.
+In an approved writing batch, use only the saved captures and observed labels
+in the supplied manifest slice. Choose images that prove the reader's steps;
+do not browse, take screenshots, or modify capture status. The capture workflow
+below applies only to a dedicated capture task or a run without an approved plan.
+
+Use this workflow only for screenshots of the product being documented (the
+`doxloop capture` command is unrelated design-reference tooling). Capture when the task prompt requires screenshots, the user explicitly
+asks for them, or `application.screenshots.policy` is `auto` and the page is a
+visible UI workflow. Do not capture when the prompt disables screenshots, when
+the policy is `off` and the prompt does not require them, or when the page has
+no meaningful visible state. Never decorate API or CLI procedures with images.
 
 ## Use the user-managed application
 
-Assume the user has already started and prepared the application. Never start,
-restart, stop, seed, reset, or reconfigure it. Never run a project startup,
-setup, database, or authentication command. Use `application.baseUrl` when it
-is configured; otherwise use the application URL supplied by the user or
-already open in the approved in-app browser. If no reachable application
-surface is available, finish the text guide without broken image links and
-report that screenshots could not be captured.
-
-Capture only the agreed application origin and its required public assets.
-Never use a real customer or production environment, change shared data, or
+The user has already started and prepared the application. Never start,
+restart, stop, seed, reset, or reconfigure it, and never run a startup, setup,
+database, or authentication command. Resolve every path against
+`application.baseUrl`. Use the Doxloop-provided `doxloop_capture` browser:
+its snapshot and interaction tools establish state, and its screenshot tool
+saves each image at the manifest's project-relative filename. That tool
+resolves the filename against the documentation project root and does not
+create directories: a missing parent folder fails with `ENOENT` and writes
+nothing. Doxloop pre-creates the guide directories for an approved plan; create
+any other parent yourself first, and read the result of every screenshot call —
+an error means no image exists.
+
+Capture only the agreed application origin with a demo or test account and
+synthetic data. Never use a production environment, change shared data, or
 operate outside the workflow being documented.
 
-## Reuse in-app browser authentication
-
-Keep authentication in the in-app browser controlled by Codex, Claude, or the
-selected agent. Do not add authentication settings to `.doxloop/project.json`
-and do not create login scripts, storage-state files, credential files, or
-environment-variable requirements.
-
-1. Open the application in the approved in-app browser and inspect the visible
-   state.
-2. If an authenticated application page is already visible, reuse that session
-   and continue without mentioning login.
-3. If the application redirects to login, first allow the browser's existing
-   session or password-manager autofill to work. The agent may select a sign-in
-   control after autofill, but must never inspect, copy, reveal, or log an
-   autofilled value.
-4. If user interaction is required, keep the login page open and ask the user
-   once to complete login, MFA, SSO, passkey, or browser confirmation directly
-   in that browser. Never ask for a password, token, OTP, cookie, recovery code,
-   or secret in chat.
-5. After login, verify a stable authenticated state such as the expected page,
-   account menu, workspace name, or application heading before capture.
-6. Keep the same browser session and context for the entire capture manifest.
-   Do not clear cookies, local storage, cache, or site data and do not open the
-   workflow in an isolated browser context.
-7. If the session expires, preserve the current manifest row, return to the
-   login checkpoint once, verify authentication again, and resume that row
-   rather than restarting or taking screenshots of the login page.
-
-Use a demo, test, or other non-production account with synthetic data. Treat
-login and account-selection screens as private operational states: exclude
-them from the guide unless the agreed reader task is specifically about login.
-
-## Plan the visual story
-
-Finish and fact-check the ordered text procedure before operating the
-application. Make every UI step atomic: one primary reader action followed by
-one observable result. Do not capture while improvising the guide.
-
-Create a capture manifest before taking the first image. Give every published
-UI step a stable step ID, including steps that intentionally have no image:
-
-| Step ID | Published action | Expected visible state | Capture? | Target | Filename | Alt text | Status |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| 01 | Open **Team settings**. | Team settings page is visible. | yes | page heading | `01-team-settings.png` | Team settings page with the heading marked as step 1 | planned |
-| 02 | Copy the workspace ID. | ID is copied; no durable visual change. | no | — | — | — | text-only |
-| 03 | Select **Invite member**. | Invitation form is open. | yes | Invite member button | `03-invite-form.png` | Invitation form opened from the Invite member button marked as step 3 | planned |
-
-The manifest is the source of truth for capture order, filenames, step marker
-numbers, alt text, and placement. Never choose screenshots opportunistically
-from whatever page happens to be open. Do not renumber captures to hide an
-intentionally text-only step: the image prefix and visual marker must match the
-published step number.
-
-For each guide step, record:
-
-1. the reader action immediately before the image;
-2. the stable visible state that proves the action succeeded;
-3. the control or region that needs attention, if any;
-4. the image filename, alternative text, and optional caption.
-
-When the user asks for a screenshot for every step, capture every step that has
-a meaningful visible UI state. Mark non-UI steps and actions with no durable
-visible change as `text-only` in the manifest and explain that decision in the
-completion summary. Otherwise capture only when an image reduces ambiguity or
-confirms an important state. Keep the application chrome and nearby labels when
-they help readers orient themselves. Prefer a viewport screenshot or a
-carefully cropped stable region; avoid very tall full-page screenshots for task
-steps.
-
-## Operate and verify the workflow
-
-Prefer stable accessible roles, labels, visible text, and product test IDs over
-fragile CSS structure. Reuse verified Playwright, Cypress, or other UI tests as
-workflow evidence when available, but do not modify or submit destructive
-production data. Process the manifest strictly from the lowest step ID to the
-highest. For each planned image:
-
-1. reset or establish the expected fixture state;
-2. perform the documented actions in their published order;
-3. wait for the expected visible outcome, not an arbitrary delay alone;
-4. dismiss only transient UI that a normal reader would not see;
-5. inspect the viewport for secrets, personal data, unstable timestamps,
-   unrelated notifications, and accidental browser content;
-6. add contextual highlighting when it materially helps;
-7. capture the image to its manifest filename;
-8. open the saved file and verify that it is the expected step, has the correct
-   marker, is legible, contains no sensitive or transient content, and is not a
-   duplicate of another step;
-9. mark the manifest row `verified` only after that inspection, then remove the
-   overlay and continue.
-
-If a capture is wrong, replace that file immediately and repeat the same
-manifest row. Do not continue and plan to sort screenshots out later. Do not
-reuse one screenshot for multiple steps unless those steps intentionally refer
-to exactly the same visible state and the prose makes that explicit.
-
-If browser automation is unavailable or the application cannot be reached,
-finish a complete text guide, do not create placeholder images or broken image
-links, and report the capture limitation.
-
-## Highlight the relevant context
-
-When `application.screenshots.highlight` is not `false`, highlight the control
-or result a reader should notice. Use a temporary browser overlay rather than
-editing product source or permanently changing application styles:
-
-- draw a 3 px high-contrast ring with 4–6 px clearance around the target;
-- add a small numbered marker matching the corresponding guide step;
-- optionally dim the rest of the viewport by no more than 18 percent;
-- keep the target, its label, validation message, and surrounding orientation
-  visible;
-- never use color alone: the numbered marker and nearby prose must identify the
-  target;
-- remove the overlay before continuing to the next application action.
-
-When the browser supports script evaluation, inject the packaged
-[highlight helper](../assets/screenshot-highlight.js), call
-`__doxloopScreenshotHighlight({ selector, step, dim })` immediately before the
-screenshot, and call `__doxloopRemoveScreenshotHighlight()` immediately after.
-Choose `selector` from a verified stable test ID, accessible label relationship,
-or other stable product evidence. The helper returns the measured target bounds
-for the capture record and never mutates product source.
-
-The ring and marker should be baked into the PNG so they work in every
-documentation generator. Do not draw arrows or labels over interactive text,
-form values, error details, or other information the reader needs.
-
-## Store and embed screenshots
-
-Follow the selected generator skill for its native public asset directory and
-image syntax. Group images under a stable guide-specific directory and use
-ordered, descriptive filenames, for example:
-
-```text
-assets/guides/invite-team-member/
-  01-team-settings.png
-  02-invite-form.png
-  03-invitation-sent.png
-```
-
-Use these default committed locations unless the existing project has an
-established equivalent:
-
-| Generator | Screenshot directory | Public/reference prefix |
-| --- | --- | --- |
-| Doxbrix | `<contentDir>/assets/guides/<guide>/` | `/assets/guides/<guide>/` |
-| Docusaurus | `static/img/guides/<guide>/` | `/img/guides/<guide>/` |
-| MkDocs | `docs/assets/guides/<guide>/` | page-relative `assets/guides/` |
-| Sphinx | `<contentDir>/_static/guides/<guide>/` | `/_static/guides/<guide>/` |
-| Hugo | `static/images/guides/<guide>/` | `/images/guides/<guide>/` |
-| VitePress | `docs/public/images/guides/<guide>/` | `/images/guides/<guide>/` |
-| Markdoc | `assets/guides/<guide>/` | `/assets/guides/<guide>/` |
-| Nextra | `public/images/guides/<guide>/` | `/images/guides/<guide>/` |
-| Starlight | `public/images/guides/<guide>/` | `/images/guides/<guide>/` |
-| Jekyll | `assets/images/guides/<guide>/` | `relative_url` from `/assets/images/guides/<guide>/` |
-| Static HTML | `site/assets/guides/<guide>/` | `/assets/guides/<guide>/` |
-
-Respect any configured base path when the generator requires relative or
-base-aware URLs. Verify the final built output contains each image; source-file
-existence alone is not sufficient.
-
-Guide screenshots are committed documentation assets. Never put them under
-`.doxloop/cache/reference/`. Embed each verified image before capturing the
-next step. Insert it inside the same ordered-list item, immediately after the
-instruction or expected-result sentence that the image proves. Do not collect
-step screenshots at the beginning or end of the guide, place an image between
-two unrelated steps, or let Markdown indentation terminate the ordered list.
-Add concise alternative text describing the useful visible state, not phrases
-such as "screenshot of". Use a caption for orientation or consequence that is
-not already obvious from the prose. Keep all essential instructions and values
-in text outside the image.
-
-For Doxbrix, prefer a captioned frame:
+## Authentication checkpoint
+
+Doxloop owns sign-in material. The prompt says which kind is available; never
+add authentication settings to `.doxloop/project.json` or create login scripts,
+storage-state files, credential files, or environment requirements.
+
+- **Recorded browser session.** `doxloop_capture` starts signed in. If a login
+  page appears, the session expired: record the affected steps as text-only
+  with the reason "saved browser session expired" and tell the user to sign in
+  again under **Settings → Visual evidence**. Do not try to sign in.
+- **Saved credentials.** On the sign-in form, type the literal names
+  `DOXLOOP_APP_USERNAME` and `DOXLOOP_APP_PASSWORD` into the username and
+  password fields with the browser type or fill-form tools; the server
+  substitutes and redacts the real values. Never guess, print, or reconstruct
+  them, type them anywhere else, or capture the filled form.
+- **Neither.** Open the application. If it redirects to login, record the steps
+  that need a signed-in screen as text-only and tell the user once that they
+  can sign in or save credentials under **Settings → Visual evidence**. Never
+  ask for a password, token, OTP, cookie, or secret in chat.
+
+After sign-in, confirm a stable authenticated state (expected page, account
+menu, workspace name) before capturing. Keep one browser session for the whole
+manifest; never clear cookies, storage, or site data. If the session expires
+mid-run with credentials available, sign in once more and resume the same
+manifest row. Login and account-selection screens are private states: exclude
+them unless the reader task is login itself.
+
+## Follow the manifest
+
+Doxloop has already written `.doxloop/screenshot-manifest.json` for an approved
+plan, with every guide and its steps staged as `status: "planned"`. Steps
+already marked `verified` with a `file` were captured by Doxloop: keep them and
+embed those images. Fill the rest in as you capture. Never delete a guide, drop
+a step, renumber captures, or rebuild the file from the images you took; a
+guide left `planned` fails the run. Each page's `visuals.startPath`,
+`visuals.workflow`, and `visuals.captureSequence` are the boundary and the
+required visual story: follow the items in order and do not collapse a
+multi-state sequence into one final-state image. If they are missing,
+contradictory, unsafe, or no longer match the application, stop capture for
+that guide and report the blocking detail.
+
+Without a plan, finish and fact-check the text procedure first, then write the
+manifest yourself before the first image (schema in
+[screenshot-manifest.md](screenshot-manifest.md)). Read that file otherwise
+only if Doxloop reports a manifest shape problem.
+
+Every step that changes what is on screen gets its own image: the entry screen,
+each dialog, drawer, tab, or expanded section a step opens, the form filled
+with safe example values, and the visible result. Steps that leave the screen
+unchanged — typing into a visible field, scrolling, focusing, hovering — share
+the previous image and are recorded as text-only. Never save the same screen
+twice inside one guide to reach a planned count; Doxloop hashes images and
+rejects repeats. Two guides may show the same screen when both document it.
+
+## Navigate, verify, capture
+
+Open each guide's `startPath` in the capture browser before forming any
+opinion about it; never conclude from source or another page's snapshot that a
+screen is empty or not distinct. An empty or unconfigured screen is still what
+the reader meets. Process steps from the lowest ID upward. For each planned
+image:
+
+1. establish the expected fixture state and perform the documented actions in
+   published order;
+2. wait for the named content, not an arbitrary delay: most applications render
+   on the client, and a capture taken straight after navigation shows a splash
+   or skeleton that Doxloop rejects as a near-blank image;
+3. snapshot only when the next action needs an element reference or a dialog,
+   menu, or drawer must be confirmed open — not as a separate check before
+   every image, never after one; a successful navigation or click already
+   confirms the state;
+4. dismiss transient UI a reader would not see, and inspect the viewport for
+   secrets, personal data, unstable timestamps, and unrelated notifications;
+5. when `application.screenshots.highlight` is not `false`, inject the packaged
+   [highlight helper](../assets/screenshot-highlight.js), call
+   `__doxloopScreenshotHighlight({ selector, step, dim })` on a stable test ID
+   or accessible-label selector, capture, then call
+   `__doxloopRemoveScreenshotHighlight()`; the 3 px ring and numbered step
+   marker are baked into the PNG and must not cover labels or values;
+6. capture to the manifest filename, confirm the call succeeded, mark the row
+   `verified`, embed the image, and move to the next row.
+
+Prefer a viewport or cropped stable region over a very tall full page and keep
+the chrome and labels that orient the reader. If a capture is wrong, replace it
+immediately and repeat the same row. You are not expected to
+open the saved PNG afterwards — Doxloop checks readability, size, blank or
+loading screens, duplicates, and embedding itself — and being unable to view an
+image is never a reason to downgrade a real capture to text-only.
+
+## Text-only rules
+
+`text-only` means a state you could not reach: sign-in required, seeded data
+missing, a workflow you cannot safely advance, or a planned item that turned
+out not to change the screen. Record a specific `textOnlyReason`, keep complete
+text instructions, and never save the screen you happen to be on under the
+name of a state you did not reach. If the browser or application is
+unavailable, finish a complete text guide with no placeholder images or broken
+links and report the limitation.
+
+## Name, store, and embed
+
+Group images under a stable guide directory with ordered, descriptive names
+(`01-team-settings.png`, `03-invite-form.png`); the number matches the
+published step, so an intentionally text-only step leaves a gap rather than
+renumbering. Doxbrix stores guide images at `<contentDir>/assets/guides/<guide>/`
+referenced as `/assets/guides/<guide>/…`; other generators use the table in
+[screenshot-manifest.md](screenshot-manifest.md). Guide screenshots are
+committed documentation assets, never `.doxloop/cache/reference/`.
+
+Embed each verified image immediately after the instruction or result it
+proves — inside the same ordered-list item or, with a step component such as
+Doxbrix `<Steps>`/`<Step>`, inside that step's own body, never collected after
+the block or between unrelated steps. Every verified capture must appear
+exactly once in its guide; delete an image that earns no place and record the
+step text-only. Alt text names the useful visible state, never "screenshot
+of"; a caption adds orientation or consequence the prose lacks; every
+essential instruction and value stays in text. For Doxbrix:
 
 ```mdx
 <Frame caption="The highlighted Invite member control opens the invitation form.">
@@ -217,35 +156,10 @@ For Doxbrix, prefer a captioned frame:
 </Frame>
 ```
 
-Use native caption or figure syntax supplied by other generators. Plain
-Markdown images are the portable fallback.
-
-## Run the screenshot completeness gate
-
-Do not finish a screenshot-enabled guide until all of these checks pass:
-
-1. Compare the final ordered procedure with the manifest row by row.
-2. Confirm every published UI step has exactly one `verified` image or an
-   explicit `text-only` reason.
-3. Confirm every verified manifest filename exists exactly once in the guide
-   and immediately follows its matching step.
-4. Confirm the filename prefix, highlighted marker, prose step number, visible
-   state, and alt text all refer to the same step.
-5. Confirm there are no unreferenced captures, broken paths, duplicate images,
-   stale screenshots, or screenshot links outside the guide-specific folder.
-6. Build the selected generator, then inspect the rendered guide from top to
-   bottom at desktop and narrow widths. Verify list numbering, image order,
-   cropping, legibility, captions, and the association between each step and
-   image.
-
-Any mismatch is a blocking defect. Fix the procedure, manifest, capture, or
-placement and rerun the entire gate; do not report the guide as complete.
-
-## Refresh without churn
-
-During update, recapture only when the documented workflow, visible label,
-layout, theme, or expected outcome changed, or when the user explicitly asks.
-Preserve filenames when the semantic step is unchanged so links and review
-history remain stable. Remove an old image only after all page references to it
-are removed. Run `doxloop test` and the generator build to catch missing assets,
-then review the rendered guide at desktop and narrow widths.
+## Resume and refresh
+
+On a resumed run the prompt lists manifest progress per guide: keep every
+verified row, file, and placement and work only on the unfinished steps. During
+update, recapture only when the workflow, label, layout, theme, or outcome
+changed or the user asks; keep filenames for unchanged steps and remove an old
+image only after its references are gone.

package/skills/doxloop-authoring/references/workflows.md

@@ -0,0 +1,76 @@
+# Workflows for runs without an approved plan
+
+Use these procedures only when no approved `.doxloop/documentation-plan.json`
+scopes the run. Every reading list in `SKILL.md` still applies.
+
+## Create
+
+Read, in addition to the start-of-task references, [references/documentation-types.md](documentation-types.md),
+[references/page-depth.md](page-depth.md), and
+[references/branding.md](branding.md).
+
+1. **Discover.** Inspect enough source to understand the reader-visible
+   product: entry points, commands, routes, configuration schemas, runtime
+   requirements, tests and fixtures that show supported workflows,
+   authentication, permissions, errors, limits, recovery paths, theme tokens
+   and public brand assets, and existing documentation that still matches.
+   Classify the product, readers, first-success path, capabilities, workflows,
+   and operational concerns, recording evidence for each conclusion.
+2. **Consult once.** Present a concise discovery summary (expert profile,
+   identity, pages grouped as must have / next / later with reasons, navigation
+   outline) as a progress update. Ask once, with at most three decisions, only
+   when a material decision is unresolved; otherwise state assumptions and
+   continue in the same run — a plan alone is never a finished create run.
+   Never ask what inspection can answer. Then update only the `documentation`
+   object in `.doxloop/project.json`.
+3. **Plan coverage.** Map reader jobs and capabilities to types, pages,
+   evidence, and gaps. Comprehensive means complete for the agreed scope, not
+   the largest page count; no filler or placeholder trees.
+4. **Author.** Improve a page that already has the right purpose; create one per
+   distinct reader job. Cover overview and a verified first-success path,
+   prerequisites and configuration, each important workflow, needed concepts,
+   public interfaces, evidence-backed troubleshooting, limitations, and next
+   steps. Add every page to native navigation, apply the identity through
+   native theme configuration, replace every generated starter page, and remove
+   every `doxloop:starter-page` marker. Do not stop after the landing page and
+   quickstart when the source supports more. Complete factual, task, editorial,
+   and accessibility passes. For a screenshot-enabled guide, finish the text
+   procedure first, then capture in manifest order.
+
+## Update
+
+1. Classify the request: source synchronization (use the prompt's change
+   summary and `git diff` against the listed baseline), a scoped content
+   change, or transformation (inspect existing pages first; an unrelated change
+   summary never redefines the scope).
+2. Find affected pages: read `.doxloop/evidence-map.json` first when it exists,
+   verify its candidates against the source, and check for pages it misses.
+3. Reuse the existing expert profile when valid. Read the routing, domain/type,
+   audience, and navigation references only when the update adds a journey,
+   changes audience or domain, or restructures IA;
+   [references/branding.md](branding.md) when theme tokens or brand
+   assets changed; [references/reference-sites.md](reference-sites.md)
+   when the design reference changed;
+   [references/screenshots.md](screenshots.md) when screenshots are
+   enabled and an affected UI workflow, label, layout, or outcome changed —
+   refresh only those images.
+4. Update all affected pages to the depth contract, preserving verified facts,
+   examples, routes, and links during transformation; inspect adjacent pages
+   for contradictions or new gaps.
+5. Preserve the brief, terminology, and structure unless the user changes them
+   or verified behavior contradicts them. Recommend new pages for gaps; ask
+   before broadening scope. Make no edit when the change is entirely internal,
+   and say why.
+
+## Review
+
+Do not edit files. Read
+[references/documentation-types.md](documentation-types.md),
+[references/branding.md](branding.md), and
+[references/quality.md](quality.md), plus the relevant expert
+templates and [references/navigation-architecture.md](navigation-architecture.md)
+when domain correctness, depth, audience fitness, or IA is in scope. Report
+blocking accuracy or usability problems, missing coverage, IA and depth
+problems, smaller clarity improvements, the evidence for each finding, and the
+hard-gate result with the scored rubric. Do not penalize omitting a generic
+topic the product does not support; do not report speculation as fact.

package/skills/doxloop-doxbrix/SKILL.md

@@ -5,18 +5,22 @@ description: Author and maintain documentation in native Doxbrix format, includi
 
 # 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.
+Produce documentation that renders natively in Doxbrix. Use it together with
+`$doxloop-authoring`, which owns what to write; this skill owns how Doxbrix
+expresses it. Translate the shared semantic top/left navigation plan into native
+Doxbrix spaces, groups, and page entries; preserve the approved information architecture.
 
 ## Read before editing
 
-1. Read `.doxloop/project.json` and confirm `generator` is `doxbrix` or absent.
+1. In a batch, use the generator and target in the supplied prompt and plan
+   slice. Otherwise 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.
+4. In a batch, use the assigned page paths and the supplied terminology. Read
+   `docs.json` only if assigned site setup. Outside batches, inspect existing
+   configuration and pages for established patterns.
 
 When creating or changing HTTP API reference, also read
 [references/api-endpoints.md](references/api-endpoints.md) and follow its
@@ -27,7 +31,8 @@ skill instead.
 
 ## Author native Doxbrix content
 
-- Write `.mdx` when using Doxbrix components.
+- Write every new page as `.mdx`, never `.md`, whether or not it uses
+  components; an existing page keeps its file name.
 - 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.
@@ -48,16 +53,33 @@ skill instead.
 Do not emit Docusaurus directives such as `:::tip`, Docusaurus theme imports, or
 `sidebars.js` entries in a Doxbrix project.
 
+## Compose professional pages
+
+Map the authoring skill's page-depth contract onto Doxbrix components:
+
+- Landing page: an opening value statement, a `<CardGroup>` with one card per
+  audience, a capability list, a `<Mermaid>` lifecycle diagram, and a closing
+  `<CardGroup>` of next steps.
+- Guides: a `<Note>` or `<Info>` for prerequisites, `<Steps>` with one
+  `<Step>` per reader action, a `<Frame>` screenshot inside every step that
+  changes the screen, a `<Check>` for the success state, `<Tabs>` for UI and
+  CLI alternatives, an `<Accordion>` for troubleshooting or edge cases, and a
+  closing card or link to the next job.
+- Reference: one heading per command, field, or operation with complete tables
+  (type, default, meaning) and a `<CodeGroup>` of realistic examples.
+- Concepts: a `<Mermaid>` diagram or comparison table and links to the tasks
+  the concept informs.
+
+Use components only where they clarify; never as decoration.
+
 ## 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.
+Map major reader surfaces to Doxbrix spaces or supported site links and
+left-navigation groups to nested `docs.json` nodes; do not create empty 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
+Treat `docs.json` at the project root as the canonical manifest for new native
+Doxbrix projects. Existing projects with a non-empty `contentDir` keep the
+manifest inside that directory, such as `docs/docs.json`. 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
@@ -66,8 +88,8 @@ 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 the confirmed application identity as [references/manifest.md](references/manifest.md)
+describes:
 
 - write colors, mode, fonts, logos, favicon, and backgrounds under `theme`;
 - copy public logos and licensed local font files into the documentation content
@@ -77,9 +99,3 @@ Use the identity and any confirmed external design profile gathered through
 
 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.