@shoalrun/cli 1.0.0 → 1.1.0

package/example-configs/facet-sections/base.yaml

@@ -0,0 +1,29 @@
+schemaVersion: 1
+site:
+  title: Service documentation
+  contentDir: content
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    version: current
+    access: { policy: public }
+readerFilters:
+  facets:
+    audience:
+      label: Audience
+      options: { customer: Customers, internal: Internal }
+outputs:
+  html:
+    shareImages: false
+    highlighting: { provider: none }
+navigation:
+  - { id: billing, doc: guide.billing }

package/example-configs/facet-sections/content/billing.mdx

@@ -0,0 +1,25 @@
+---
+id: guide.billing
+title: Billing
+summary: Understand billing and check operational status.
+slug: /
+audiences: [customer, internal]
+---
+
+## Review a bill
+
+Open the billing page and choose the billing period. Check the total and download
+the statement before contacting support about a charge.
+
+<ForFacet audience="internal">
+
+## Check the retry queue
+
+Before replaying a failed billing job, check whether the original request
+completed. Record the job identifier and use the team's approved replay procedure.
+
+</ForFacet>
+
+## Get help
+
+Include the statement identifier and billing period in your support request.

package/example-configs/facet-sections/customer.config.yaml

@@ -0,0 +1,4 @@
+extends: [./base.yaml]
+site:
+  title: Customer documentation
+  contentFilter: { audience: [customer] }

package/example-configs/facet-sections/docs.config.yaml

@@ -0,0 +1,3 @@
+extends: [./base.yaml]
+site:
+  title: Complete documentation

package/example-configs/faceted-sites/README.md

@@ -19,8 +19,10 @@ all applicable values, or supply appropriate `readerFilters.typeDefaults`.
 Unknown facets, unknown choices, empty selectors, and selections with no pages
 fail the build. Omit `contentFilter` to publish all otherwise eligible pages.
 
-Selection applies to whole authored and generated pages before rendering. A
-selected page retains its complete body, including reader-marked sections.
+Selection applies to authored and generated pages before rendering. On a selected
+page, `<ForFacet>` blocks also follow the build selection. Unmarked sections stay
+included, and `<ReaderSection>` content remains published. See
+[the audience section example](../facet-sections/README.md).
 Reader controls do not bring excluded pages back. Keep links and navigation
 within the selected set; missing targets fail validation. Configure API sources
 and operation selection separately: publishing an API contract may expose the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoalrun/cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
@@ -40,6 +40,7 @@
     "DEPLOYMENT-PROFILES.md",
     "schemas/code-reference.schema.json",
     "adapters/python",
+    "adapters/typescript",
     "!**/__pycache__/**",
     "!adapters/python/test_*.py",
     "schemas/content-export.schema.json",

package/skills/shoalrun-author/SKILL.md

@@ -5,6 +5,15 @@ description: Write or revise documentation in an existing Shoalrun project using
 
 # Author Shoalrun documentation
 
+## Before you start
+
+- Read project `AGENTS.md`, writing guidance, and installed-version references before editing.
+- Preserve IDs, routes, access, and original dates; update `updated` and required taxonomy for edited pages.
+- Explain HTML, Markdown, and agent behavior when documenting components or presentation features.
+- Keep navigation, relationships, generated sources, and publication/build selection consistent.
+- Validate the affected set; build once per input set, inspect both representations, and reuse that output for preview.
+
+
 Use normal working-tree file tools. Shoalrun supplies project discovery, canonical references, isolated validation and snapshot previews; your harness supplies planning, evidence gathering, writing and permissions. No additional authoring model key or replacement-file JSON is required. Preserve unrelated local edits and never hand-edit generated output.
 
 ## Discover the task and its policy
@@ -29,6 +38,10 @@ For source-code library or SDK references, read [references/code-api-references.
 
 For independently versioned products, cross-product reuse, product-scoped delivery, or feature availability labels, read [references/publications.md](references/publications.md). Preserve product/channel/version/language identity, distinguish publication membership from feature grants, and check installed-version support before using new fields. Availability labels describe support; they don't filter the published content.
 
+## Build-time facet selection
+
+For builds selected by configured facets, read [references/facet-selection.md](references/facet-selection.md). Use `contentFilter` for pages and `<ForFacet>` for additional sections. Keep build-time omission distinct from the presentation-only `<ReaderSection>` and from customer feature grants.
+
 ## Customer editions and feature selection
 
 For SKU-selected or white-label documentation, read [references/customer-editions.md](references/customer-editions.md) before editing requirements, manifests, profiles, branding, or edition validation. Use the deployment's external profile, keep customer records out of shared source, and classify pages by feature IDs. Shared pages can use `<ForFeature>` for feature-specific sections. Preserve the project's strict-classification policy and pass the same `--profile` to baseline, validation, build, export, and development preview; a default-context pass does not verify a customer edition.

package/skills/shoalrun-author/references/code-api-references.md

@@ -1,9 +1,13 @@
 # Code API reference authoring
 
-Read `guide.code-api-references` and `reference.code-api-references` from the installed package's bundled docs when present. Check installed-version support; the feature starts in 1.0.0. A source checkout also provides `CODE-REFERENCES.md` and a runnable `examples/code-references` project.
+Read `guide.code-api-references` and `reference.code-api-references` from the installed package's bundled docs when present. Check installed-version support for the chosen adapter and fields; base code references start in 1.0.0. A source checkout also provides `CODE-REFERENCES.md` and a runnable `examples/code-references` project.
 
 Use `codeReferences` for a language library or SDK, and `apis` for OpenAPI HTTP endpoints. A converter writes the versioned snapshot; normal builds never invoke it. The optional Python adapter requires an explicitly prepared Python 3.11+ environment with its pinned requirements. Keep extraction roots narrow and don't enable runtime inspection or external discovery to make an unsupported package appear to work. Other languages can provide their own converter; don't claim a bundled Kotlin extractor.
 
+The bundled TypeScript adapter requires Shoalrun 1.1.0 or newer. For TypeScript, confirm the installed package includes `adapters/typescript/shoalrun-reference.mjs`. Install `typescript@5.9.3` explicitly in the project supplying `tsconfig.json`, then run the adapter with `--project`, `--entry`, stable `--module`, `--out`, and optional narrower `--root`. Entry paths resolve against the configuration; output resolves against the current directory. Use source or built declaration files. Never infer support from the base code-reference version alone.
+
+Keep the adapter's failure checks: excluded structural members and copied defaults can require a separate public type/value; unsupported conditional expansions fail. Don't remove visibility annotations to force extraction. Review inferred signatures, every overload, optional/readonly markers, copied defaults, and grouped/complete output for excluded details. Extraction doesn't sanitize arbitrary strings or authorize publication. The digest includes effective options and external type dependency bytes, and graph limits apply after loading rather than providing process isolation. Output/input collisions, including symlinks, fail before writes.
+
 Run `shoalrun references check FILE`, inspect the snapshot's public symbols and prose, then configure the catalog. Snapshot descriptions are inert Markdown; MDX, project directives, relative links, and images aren't supported. Preserve exact symbol IDs and use explicit document IDs/slugs when public identities must survive a rename. Keep snapshots in the project and regenerate them after source changes.
 
 Choose `layout: symbols`, `classes`, or `modules` by reading needs. All retain individual symbol URLs. Add `singlePage` only when a complete reference is useful; configure its ID, slug, title, summary, and optional metadata, then link that ID in navigation. Group class or module pages in navigation instead of listing every symbol when a shorter menu is wanted.

package/skills/shoalrun-author/references/facet-selection.md

@@ -0,0 +1,48 @@
+# Build-time facet selection
+
+ForFacet requires Shoalrun 1.1.0 or newer. Check the installed compiler's support before using `<ForFacet>`; an older bundled documentation snapshot doesn't establish availability. Use `readerFilters.facets` to declare choices, `site.contentFilter` to select a site's pages, and `<ForFacet>` to omit unmatched sections. No customer profile or SKU manifest is needed.
+
+**Unmarked sections remain included. Pages without a mark for a selected facet are excluded.** Give a shared page all applicable page-level marks; a section guard can't bring an excluded page back.
+
+```yaml
+readerFilters:
+  facets:
+    audience:
+      label: Audience
+      options: { customer: Customers, internal: Internal }
+site:
+  contentFilter: { audience: [customer] }
+```
+
+```mdx
+---
+id: guide.billing
+title: Billing
+summary: Understand billing and operational checks.
+type: guide
+slug: /billing
+audiences: [customer, internal]
+---
+
+Shared billing instructions.
+
+<ForFacet audience="internal">
+
+## Operational checks
+
+Check the retry queue before replaying failed jobs.
+
+</ForFacet>
+```
+
+Every authored facet must match; whitespace-separated choices within an attribute are alternatives. An unselected facet passes automatically. No build filter includes every valid block. Nested guards AND, including `<ForFeature>` guards. Only literal positive matches are accepted; don't invent expressions, exclusions, or replacement semantics. An unfiltered build contains both blocks if an author writes separate customer and internal versions.
+
+`<ReaderSection>` uses comma-separated choices and only changes browser visibility: its content still ships. A retained ReaderSection using a build-selected facet produces `reader-section-build-facet`; check whether the author intended omission. Don't suppress the warning by relabeling private content.
+
+Portable export targets select independently of the website: give each target its own `contentFilter` when it must omit sections. PDF exports inherit the site's filter unless the target overrides it. Check the exact site, export, and PDF selection rather than assuming one site's result proves every artifact.
+
+Validate both a filtered build and an unfiltered build. Confirm the extra text and headings are absent from the filtered HTML, Markdown, discovery/search output, and copied assets. Check snippet instances and application exports when affected. Excluded guards still validate their facet names and choices, including nested excluded branches, but their ordinary snippet/API/image invocations don't expand. Globally registered snippet files and plugins still load and validate.
+
+Read the private `.shoalrun/content-selection.json` receipt for the last successful artifact's decisions and warnings. Its target identifies which artifact was selected; the `receipt` path points to the artifact-specific copy. Keep these reports out of served files. Facet catalogs and separately published API contracts aren't redacted by removing a section. Build-time omission isn't deployment authentication.
+
+For selection changes, use an isolated canary fixture: unique text, heading, snippet, image, and API markers must appear in their included artifact and be absent from every excluded artifact. Scan all distributed files, not just article HTML; decode prepared-PDF asset payloads and inspect generated PDF text when those outputs are enabled. Interleave audience/product builds and independently filtered exports, check publication-scoped snippet metadata, and verify an unchanged sibling output plus broad-to-narrow replacement in a temporary directory. Never deploy a retained last-good artifact after a failed build for a different selection.

package/skills/shoalrun-brand/SKILL.md

@@ -5,6 +5,15 @@ description: Apply a visual brand to a Shoalrun documentation site or local demo
 
 # Brand a documentation site
 
+## Before you start
+
+- Read project policy and use supplied brand evidence for visual decisions.
+- Preserve content, IDs, routes, navigation, and publication/profile selection.
+- Configure palette, fonts, logos, and supported settings before adding scoped CSS.
+- Check text, inputs, menus, search results, and keyboard focus in each requested mode.
+- Reuse validated output until inputs change; review Markdown and PDF effects when affected.
+
+
 Inspect the target project's configuration, styles, assets, installed package version, and applicable project instructions. Preserve documentation, routes, navigation, publication selection, and existing edits. For a separate demo, copy source into a new directory and keep its build output separate. Visual branding doesn't establish product facts; retain sample-content labels and don't invent product capabilities or release histories.
 
 ## Establish the brand

package/skills/shoalrun-component-author/SKILL.md

@@ -5,6 +5,15 @@ description: Create or repair Shoalrun component packages with shared documentat
 
 # Author a Shoalrun component
 
+## Before you start
+
+- Read project policy and the installed component contract before changing a package.
+- Keep essential content in one shared model for HTML and Markdown.
+- Check attributes, dependencies, instance data, and state isolation.
+- Verify keyboard behavior and the no-JavaScript fallback for browser enhancements.
+- Update required companion docs and metadata; reuse verified output until inputs change.
+
+
 Read project policy and `shoalrun docs read guide.custom-components` from the installed CLI. Distinguish using an existing component from developing its package. Page authors need the documented tag and attributes; component developers own the manifest, implementation, dependencies, and tests. Keep task-specific prose in MDX.
 
 Start with the smallest content model that solves the request. Export `defineComponent({ attributes?, children?, content })` from `@shoalrun/cli/components`. The required synchronous `content()` function receives validated attributes and opaque authored children. Return the children, supported `content` helpers, or `{ content, data }`. Do not construct compiler nodes or add separate HTML/Markdown renderers. Shoalrun renders the same shared content into both formats; authors must review its adequacy.

package/skills/shoalrun-pdf/SKILL.md

@@ -5,6 +5,15 @@ description: Style and export Shoalrun pages or publications as PDFs, including
 
 # Style and export documentation PDFs
 
+## Before you start
+
+- Check the installed CLI, print settings, and required browser before exporting.
+- Keep product, version, language, profile, and build filters consistent with the requested artifact.
+- Use local print assets with appropriate rights and keep output separate from source.
+- Inspect rendered pages, extracted text, links, and absence of excluded content.
+- Reuse each verified artifact until inputs change; enable download actions only within the requested scope.
+
+
 Inspect the documentation project's instructions, installed CLI, content selection, and existing print assets. Check `shoalrun export --help` before using PDF options; a skill folder alone doesn't establish installed-version support. Use the project's installed CLI and package references without requiring a framework checkout. Preserve existing source, routes, IDs, and unrelated edits.
 
 ## Choose the publication and output

package/skills/shoalrun-recipes/SKILL.md

@@ -5,6 +5,15 @@ description: Write or revise task-oriented how-tos, reusable ingredients, recipe
 
 # Write Shoalrun recipes
 
+## Before you start
+
+- Choose the reader goal: reusable ingredient, complete recipe, or cookbook selection.
+- Find the maintained source before editing a generated recipe.
+- Preserve IDs and original dates; set `updated` and required project taxonomy.
+- Keep task handoffs, navigation, relationships, and representation explanations complete.
+- Build once per input set; check the full procedure in HTML and Markdown and reuse its output.
+
+
 Start with the reader's goal and an observable success condition. Use `how-to` for a task page, or `recipe` when it participates in recipe composition or cookbook choices. Both need practical actions and an observable result. Preserve the user's requested format and established page IDs and routes. Use `explanation` for conceptual discussion and `reference` for exact facts; an existing how-to does not need an automatic type migration.
 
 The CLI includes overrideable `recipe`, `ingredient`, and `cookbook` templates; scaffold with `shoalrun scaffold <template> -n <target>` without project registration.

package/skills/shoalrun-setup/SKILL.md

@@ -5,6 +5,15 @@ description: Start a Shoalrun documentation project from a working example, conf
 
 # Set up Shoalrun docs
 
+## Before you start
+
+- Inspect the existing project and preserve its source and local edits.
+- Use a supported starter and the project’s installed CLI; verify unfamiliar settings.
+- Set publication identity, access, and required page metadata and taxonomy deliberately.
+- Check navigation, API bindings, and essential content in HTML and Markdown.
+- Build into a dedicated output directory and reuse that build for preview.
+
+
 First inspect the target repository for an existing `docs.config.yaml`, content, OpenAPI files, and build scripts. Preserve an existing project rather than copying a starter over it. Ask for missing publication choices only when they affect the first build, such as the intended API version or whether pages are ready to be public.
 
 When adapting existing documentation, start with a connected, representative set of pages. Identify each page's reader goal and choose native structures accordingly: `Fields` for authored configuration or parameter lists, source-backed schemas and references for OpenAPI contracts, `Steps` for titled procedures, and document cards for reading paths. Read the matching bundled component references before writing syntax. Preserve IDs, routes, examples, defaults, bounds, and the distinction between an optional value and a nullable one. A successful build does not establish that these meanings survived.

package/skills/shoalrun-walkthrough/SKILL.md

@@ -5,6 +5,15 @@ description: Turn notes, a tutorial, or a piece of code into a Shoalrun Walkthro
 
 # Write a Shoalrun walkthrough
 
+## Before you start
+
+- Read the installed Walkthrough contract and the actual source being explained.
+- Choose separate complete code steps or one shared block to match the material.
+- Keep each explanation and highlight range consistent with the code shown.
+- Preserve page IDs and dates; update `updated`, required taxonomy, and companion links when editing a page.
+- Build once per input set; inspect complete Markdown and interactive HTML, then reuse the preview.
+
+
 Read the component guide first with `shoalrun docs read guide.component.walkthrough`. It has the exact syntax, attributes, and build errors. Then read the source material: the user's notes, the guide being converted, and any code files it names.
 
 Choose the mode from the material. Use separate steps, each with its own complete code, when the code grows or changes from step to step. Use one shared code block with a `highlight` per step when the steps explain parts of a single file. Use the default `scroll` layout for code that builds up in order, and `layout="spotlight"` for reference material that readers jump around in. A list of steps without code is an ordinary numbered list, not a walkthrough.