@shoalrun/cli 0.1.0-alpha.14 → 0.1.0-alpha.16

package/dist/site-identity.js

@@ -0,0 +1,69 @@
+export function validateHeader(value) {
+    if (value === undefined)
+        return { links: [] };
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('site.header must be a mapping');
+    const { links = [], ...extra } = value;
+    if (Object.keys(extra).length)
+        throw new Error(`site.header does not accept ${Object.keys(extra).join(', ')}`);
+    if (!Array.isArray(links))
+        throw new Error('site.header.links must be a list');
+    return {
+        links: links.map((link, index) => {
+            const where = `site.header.links[${index}]`;
+            const { style = 'link', ...rest } = (link && typeof link === 'object' && !Array.isArray(link) ? link : {});
+            const checked = validateSiteLink(link, where, rest);
+            if (style !== 'link' && style !== 'button' && style !== 'primary')
+                throw new Error(`${where}.style must be link, button, or primary`);
+            return { ...checked, style };
+        })
+    };
+}
+// Header and footer links share one rule: a label and a site path, http(s) URL, or mailto link.
+function validateSiteLink(link, where, fields = link) {
+    if (!link || typeof link !== 'object' || Array.isArray(link))
+        throw new Error(`${where} must be a mapping`);
+    const { label, href, ...rest } = fields;
+    if (Object.keys(rest).length)
+        throw new Error(`${where} does not accept ${Object.keys(rest).join(', ')}`);
+    if (typeof label !== 'string' || !label.trim())
+        throw new Error(`${where}.label is required`);
+    if (typeof href !== 'string' || !/^(\/|https?:\/\/|mailto:)/.test(href))
+        throw new Error(`${where}.href must be a site path, http(s) URL, or mailto link`);
+    return { label, href };
+}
+export function validateFooter(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('site.footer must be a mapping');
+    const { columns = [], links = [], text, ...extra } = value;
+    if (Object.keys(extra).length)
+        throw new Error(`site.footer does not accept ${Object.keys(extra).join(', ')}`);
+    if (!Array.isArray(columns))
+        throw new Error('site.footer.columns must be a list');
+    if (!Array.isArray(links))
+        throw new Error('site.footer.links must be a list');
+    if (text !== undefined && (typeof text !== 'string' || !text.trim()))
+        throw new Error('site.footer.text must be non-empty text');
+    const footer = {
+        columns: columns.map((column, index) => {
+            const where = `site.footer.columns[${index}]`;
+            if (!column || typeof column !== 'object' || Array.isArray(column))
+                throw new Error(`${where} must be a mapping`);
+            const { title, links: columnLinks, ...rest } = column;
+            if (Object.keys(rest).length)
+                throw new Error(`${where} does not accept ${Object.keys(rest).join(', ')}`);
+            if (typeof title !== 'string' || !title.trim())
+                throw new Error(`${where}.title is required`);
+            if (!Array.isArray(columnLinks) || !columnLinks.length)
+                throw new Error(`${where}.links must list at least one link`);
+            return { title, links: columnLinks.map((link, linkIndex) => validateSiteLink(link, `${where}.links[${linkIndex}]`)) };
+        }),
+        links: links.map((link, index) => validateSiteLink(link, `site.footer.links[${index}]`)),
+        ...(typeof text === 'string' ? { text } : {})
+    };
+    if (!footer.columns.length && !footer.links.length && !footer.text)
+        throw new Error('site.footer needs columns, links, or text');
+    return footer;
+}

package/dist/vercel.d.ts

@@ -3,6 +3,7 @@ import type { BuildProvenance } from './build-info.js';
 import { type AskFunctionResult } from './vercel-function.js';
 export declare function buildVercel(configFile: string, outputDirectory: string, provenance?: BuildProvenance, options?: {
     chat?: boolean;
+    profile?: string;
 }): Promise<{
     documents: number;
     output: string;

package/dist/vercel.js

@@ -30,7 +30,9 @@ async function removeStaleFunctions(directory, keep = new Set()) {
 export async function buildVercel(configFile, outputDirectory, provenance = {}, options = {}) {
     const output = path.resolve(outputDirectory);
     const staticDirectory = path.join(output, 'static');
-    const manifest = await compile(configFile, staticDirectory, provenance);
+    if (options.profile && options.chat)
+        throw new Error('Profiled Vercel builds do not support chat functions yet');
+    const manifest = await compile(configFile, staticDirectory, provenance, { profile: options.profile });
     const basePath = manifest.basePath;
     const functionsDirectory = path.join(output, 'functions');
     const mcp = await addMcpFunction({ staticDirectory, functionsDirectory });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoalrun/cli",
-  "version": "0.1.0-alpha.14",
+  "version": "0.1.0-alpha.16",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
@@ -33,6 +33,7 @@
     "skills",
     "README.md",
     "AUTHORING.md",
+    "DEPLOYMENT-PROFILES.md",
     "schemas/content-export.schema.json",
     "schemas/content-rest.openapi.json",
     "CHANGELOG.md",

package/skills/shoalrun-author/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: shoalrun-author
-description: Write or revise documentation in an existing Shoalrun project using the agent's own model, native file edits, and provider-free project, validation, and preview tools. Use for pages and their required navigation, relationships, API links, snippets, or project checks.
+description: Write or revise documentation in an existing Shoalrun project using the agent's own model, native file edits, and provider-free project, validation, and preview tools. Use for pages and their required navigation, relationships, API links, snippets, customer editions, or project checks.
 ---
 
 # Author Shoalrun documentation
@@ -21,6 +21,10 @@ When reading a published site through Markdown, follow topic-index links when pr
 
 Read `reference.authoring-workspace` for tool contracts and `guide.authoring-workspace` for the working-tree procedure. Before unfamiliar syntax, check the relevant component attributes, configuration structure, or asset-handling contract instead of assuming another tool’s conventions. For MDX components, read their canonical reference; `<Step>` belongs inside `<Steps>` for an ordinary titled procedure, while your harness's task plan is separate. Read implementation/specification evidence with your harness's permitted tools; record the sources for changed claims. Bundled guidance does not establish a consumer project's facts.
 
+## 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 product-specific sections. Preserve the project's strict-classification policy and pass the same `--profile` to baseline, validation, build, and export; a default-context pass does not verify a customer edition.
+
 ## Record scope and edit
 
 Before editing, capture the current state with `docs baseline --out <new-baseline> --config <config>`. Put baselines inside the project's excluded `.shoalrun` directory or outside the project. This includes earlier dirty/untracked files rather than comparing with Git HEAD. Retain the corresponding before-content/task diff with your harness; a baseline stores digests, not earlier text. For an existing rendering failure, reproduce its located finding before repairing it.

package/skills/shoalrun-author/references/customer-editions.md

@@ -0,0 +1,164 @@
+# Author customer documentation editions
+
+Use this workflow when a project selects documentation by purchased products or
+features, including grandfathered access and deployment-owned branding. Keep
+commercial selection in profiles and feature IDs in authored content.
+
+## Establish the edition context
+
+Check the installed CLI's `shoalrun --help` and `shoalrun docs --help` for `--profile`
+before using this workflow. Deployment profiles require `0.1.0-alpha.15` or later with this capability.
+Do not silently upgrade the project's pinned package. The package's
+`DEPLOYMENT-PROFILES.md` is the configuration reference; use
+`docs read guide.deployment-profiles` when that guide exists in the bundled
+snapshot. Do not assume a newly implemented feature is in an older snapshot.
+
+Read the existing shared `profiles` configuration and SKU manifest. Preserve
+immutable SKU revisions; use the purchase's explicit revision rather than
+substituting today's bundle. SKU grants and direct `features` are additive.
+Grandfathered features need no SKU. `deprecated` and `retired` labels do not
+revoke grants, and feature grants do not select older documentation versions.
+
+Use the one profile path supplied for the deployment. Keep real customer profiles,
+branding, reports, and captured snapshots outside public source control and served
+output. Do not introduce a central customer registry or scan adjacent deployments.
+If the profile is unavailable, continue shared-source work and report which edition
+checks remain unverified; do not fabricate real purchases or remove `required`.
+
+For a new synthetic example, these are complete selection inputs:
+
+```yaml
+# Shared sku-manifest.yaml, beside docs.config.yaml
+schemaVersion: 1
+features:
+  analytics: {}
+  reports.classic: {lifecycle: deprecated}
+skus:
+  professional:
+    revisions:
+      "2026-10": {features: [analytics]}
+```
+
+```yaml
+# Shared docs.config.yaml fragment; retain the project's other settings
+profiles:
+  manifest: ./sku-manifest.yaml
+  required: true
+  pruneNavigation: true
+  requireClassification: true
+```
+
+```yaml
+# Deployment-owned profile outside the shared repository
+schemaVersion: 1
+skus:
+  - {id: professional, revision: "2026-10"}
+features: [reports.classic]
+```
+
+Direct-only profiles can omit `skus`; `features: []` with no SKU grants selects
+shared content only. Missing required input, unknown IDs/revisions, and `null`
+grant lists fail rather than falling back to another edition. Profile paths resolve
+from the invocation directory; declared logo/favicon paths resolve from the profile
+directory and must remain inside it. Branding uses bounded existing `site`, `theme`,
+and snippet `variables` settings, not arbitrary config merges. Profiles cannot
+replace content sources, plugins, access policy, or navigation labels.
+
+## Choose page and section requirements
+
+In normal mode, a page with no authored or inherited `requires` is shared after
+ordinary publishing rules. Do not infer requirements from folders, product tags,
+SKU names, or navigation labels.
+
+With `profiles.requireClassification: true`, each public source page in the shared
+enabled publications must explicitly declare either `shared: true` or `requires`.
+The check precedes customer feature/publication selection. Drafts and disabled
+shared publications do not need classification for that build. Inherited
+requirements still restrict a page but do not satisfy classification. `shared`
+cannot appear in defaults/enforced settings; `shared: false` and combining
+`shared: true` with page requirements are invalid. Review unclassified pages
+named in errors; do not automatically mark them shared or disable the policy.
+
+```yaml
+# Shared page frontmatter fragment
+shared: true
+```
+
+```yaml
+# Feature-specific page frontmatter fragment
+requires:
+  allOf: [analytics]
+```
+
+Requirements name feature IDs, not SKUs. Use `allOf` when every feature is needed
+and `anyOf` when one suffices; if both clauses appear, both must pass. Lists are
+nonempty. Unmet page requirements omit the whole page.
+
+A shared page may contain product-specific sections:
+
+```mdx
+These setup instructions apply to every customer.
+
+<ForFeature allOf="analytics">
+
+## Configure Analytics
+
+Instructions for customers with Analytics.
+
+</ForFeature>
+
+These troubleshooting tips apply to every customer.
+```
+
+`ForFeature` is a block with literal whitespace-separated `allOf`/`anyOf` feature
+IDs. Excluded blocks contribute no text, links, snippets, API embeds, or images.
+Put links to optional pages inside matching conditions. A matching inner block
+cannot restore an excluded page. Ungated text on shared pages remains shared:
+classification catches missing metadata, not incorrect decisions or paragraphs.
+
+Generated API references accept explicit `shared: true` or `requires` on the API
+definition beside `generateReferences`, or `x-shoalrun-shared: true` /
+`x-shoalrun-requires: {allOf: [analytics]}` on an OpenAPI operation. API-level
+requirements still apply. Classify differing operations individually; ordinary
+frontmatter defaults do not satisfy generated classification. Authored API pages
+follow the source-page rule. Profile builds require focused operation contracts;
+full raw-source publication and standalone schema embeds are unsupported.
+
+## Validate the selected edition
+
+Capture the baseline before editing and pass the same explicit profile during
+validation, build, and export. From the project directory:
+
+```sh
+shoalrun docs baseline --config docs.config.yaml \
+  --out .shoalrun/edition-before.json --profile /run/config/docs-profile.yaml
+
+# Edit source, then validate with the selected deployment context.
+shoalrun docs validate --config docs.config.yaml \
+  --baseline .shoalrun/edition-before.json --profile /run/config/docs-profile.yaml
+
+shoalrun build docs.config.yaml edition-dist --profile /run/config/docs-profile.yaml
+shoalrun export docs.config.yaml --out edition-content \
+  --profile /run/config/docs-profile.yaml
+```
+
+Use explicit `--file`/`--id` selectors if no baseline exists. Apply the authoring
+skill's applicable project checks, review, preview, and freshness workflow to the
+returned report. Snapshot capture includes the external profile and its declared
+assets; changing them invalidates the evidence. Export still needs its normal
+publication selection when multiple combinations are enabled. `dev` and
+checked-plan authoring do not resolve deployment editions; use build/serve or
+snapshot validation/preview. Preview URLs and artifacts may contain customer data.
+
+Check both included and excluded content in HTML, Markdown, search/discovery,
+focused API contracts, and exports. Use synthetic no-grant, relevant single-feature,
+and combined-feature profiles when changing shared selection logic; do not invent
+customer records. Confirm unclassified content fails in strict mode, shared prose
+remains, and excluded markers/assets are absent from output files. Selected prose
+links must resolve; known excluded navigation entries prune only when configured.
+The private `.shoalrun/profile-selection.json` receipt is not a public artifact.
+
+Read coverage: pages excluded by the profile have not had their rendered content
+checked. Validate a context that includes changed gated content before claiming
+it is verified. Reports establish selection and validation, not authentication;
+the deployment controls customer access to each resulting edition.

package/skills/shoalrun-recipes/SKILL.md

@@ -11,6 +11,8 @@ The CLI includes overrideable `recipe`, `ingredient`, and `cookbook` templates;
 
 Read `shoalrun docs read guide.recipes-overview`, then `guide.recipe-drafts` for composition or `guide.cookbooks` for choices. In a source checkout, use `node framework/dist/cli.js` in place of `shoalrun` after compiling the framework. Inspect the target project's config, neighboring pages, and existing ingredients before writing.
 
+When recipes or ingredients vary by purchased features, read [the customer-edition workflow](../shoalrun-author/references/customer-editions.md). Apply page classification to the final recipe source, use `<ForFeature>` for feature-specific sections, and validate editions that include each changed conditional branch. Do not assume a shared-page build checks an excluded recipe or ingredient branch.
+
 Choose only the layers the task needs:
 
 - **Recipe:** write a complete page with prerequisites, ordered actions, explicit value handoffs, failure guidance, and a final success check. A recipe can be authored directly; ingredients are optional.

package/skills/shoalrun-setup/SKILL.md

@@ -11,6 +11,8 @@ When adapting existing documentation, start with a connected, representative set
 
 Use `shoalrun init <directory> --starter minimal` for a small site or `--starter api-docs` for a parcel API site with guides, generated references, and focused contracts. Use `--starter showcase` for a fuller Cedar Parcel handbook with component examples, diagrams, reader views, a landing page, local-workflow cookbook, and generated API references. All three starters build without provider credentials. The command copies a bundled example without overwriting existing files. From the source checkout, use `node framework/dist/cli.js init <directory> --starter <name>` from the repository root. Replace fixture names, prose, API files, navigation, and example domains. Keep `docs.config.yaml` as the entry point. Consult the Shoalrun config reference for unfamiliar keys; do not invent config fields or assume that a package has been published to npm.
 
+For customer-specific or white-label editions, read [the customer-edition workflow](../shoalrun-author/references/customer-editions.md) before configuring selection. Keep the SKU manifest shared and the selected customer profile in its deployment environment. Check CLI support before using `--profile`, preserve strict-classification choices, and use that profile for validation and build/serve; `dev` does not resolve deployment editions.
+
 Run scaffolding from the project directory or use an absolute target path. Passing `--config` does not rebase `scaffold -n` against that config's directory. Resolve scaffold placeholders and remove unused optional sections while retaining the page's intended identity and draft access.
 
 For a specific setting or workflow, run `shoalrun docs search "<topic>"`, then `shoalrun docs read <document-id>` to load the matching generated Markdown. Use these bundled docs before guessing at a command or config key.
@@ -31,4 +33,6 @@ For a new OpenAPI source, read `guide.api-references` and complete its API-sourc
 
 Check the generated HTML, Markdown twins, and `documents.json`. Confirm navigation and API links resolve, and inspect assets inside the components that contain them. Run `shoalrun audit docs.config.yaml` when project checks or API audits are configured; documentation behavior tests can use Doc Detective through `audit.tests` or another external CLI.
 
+For optional semantic search, use `outputs.html.search.provider: semantic` (available since `0.1.0-alpha.16`) with `retrieval.embeddings`; do not generate a custom browser adapter for Shoalrun's own endpoint. Build the site, run `shoalrun index <output> --embed --config docs.config.yaml`, then `shoalrun serve <output> --search --config docs.config.yaml` with the provider key only in the environment. Confirm the endpoint returns `mode: vector`; a visible result or keyword fallback does not prove semantic retrieval. Selecting the browser provider does not provision production hosting, and profiled Vercel chat-function builds remain unsupported.
+
 Report the files created, commands run, and anything still needing an owner decision. Do not deploy, publish a release, or claim factual accuracy from a successful build alone.

package/styles/site.css

@@ -71,6 +71,8 @@ button{cursor:pointer}
 @media(max-width:48rem){.footer-inner{padding:2rem 1.1rem 1.5rem}.site-footer a{min-height:2.75rem}}
 @media print{.footer-columns,.footer-links{display:none}.site-footer{background:none}}
 .brand{display:flex;align-items:center;gap:.7rem;font-weight:750;font-size:1rem;letter-spacing:-.025em;color:var(--color-ink);overflow-wrap:anywhere;min-width:0}
+.brand-custom::before{display:none}
+.brand-logo{display:block;flex:none;max-width:8rem;max-height:2rem;object-fit:contain}
 .brand::before{content:"";flex:none;width:.75rem;height:.75rem;border-radius:50% 50% 50% 0;background:var(--color-accent);transform:rotate(-45deg)}
 .edition{font-family:var(--font-code);font-size:.72rem;color:var(--color-header-muted);border:1px solid var(--color-header-border);border-radius:var(--radius-small);padding:.25rem .65rem;overflow-wrap:anywhere;max-width:100%}
 .layout{max-width:var(--width-site);margin:auto;display:grid;grid-template-areas:"side main rail";grid-template-columns:minmax(12rem,14rem) minmax(0,1fr) minmax(12rem,15rem);gap:clamp(1.5rem,3vw,3rem);padding:2.75rem 2rem 6rem}

package/agent-docs/publish/content-export.sections/upgrade-an-existing-integration.md

@@ -1,34 +0,0 @@
----
-id: guide.content-export
-title: Export content into your application
-summary: Export selected documentation and assets for your application.
-type: how-to
-area: publishing
-subarea: publishing-builds
-canonical: /publish/content-export
----
-
-# Export content into your application
-
-> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
-
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
-
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
-
-**Updated: 2026-10-29.**
-
-Parent page: [Full Markdown page](/publish/content-export.md)
-
-Keep application help and your documentation website in one content source. `shoalrun export` produces a directory of resolved Markdown, passive HTML fragments, referenced assets, and a manifest. Your application owns the help drawer, onboarding screen, or other interface that displays the content. It does not need a Shoalrun browser runtime.
-
-## Upgrade an existing integration
-
-If an existing bundle contains `manifest.documents`, upgrade the CLI and rebuild the export before using this guide's loader. Update custom consumers to the resource contract:
-
-- Read `manifest.resources` instead of `manifest.documents`.
-- Select page resources with `ref.kind === 'page'` and `ref.documentId` instead of a document's `id`.
-- Route links with `kind: resource` through their typed `ref`, rather than `kind: document` and `documentId`.
-- Read file paths from the rebuilt manifest; do not retain paths from the old bundle.
-
-The `documents` configuration selector remains shorthand for whole pages. Use [resource selectors](https://www.shoalrun.com/content-delivery/select.md) when selecting approved sections or named snippet instances.