Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(cli): give every doc a named home; authoring owns integration authoring (#7835)

Joey641d08e46064
diff --git a/.changeset/docs-authoring-home.md b/.changeset/docs-authoring-home.md
new file mode 100644
index 0000000000..25c5e526ff
--- /dev/null
+++ b/.changeset/docs-authoring-home.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] Everything an integration author reads now lives under one home, `astryx docs authoring`: the integration guides' routes moved from `cli/integrations/…` to `authoring/…` (for example, `cli/integrations/quick-start` is now `authoring/quick-start`), beside the field reference at `astryx docs authoring/field-reference`. `astryx docs authoring <name>` still opens one field reference section, and an old `cli/integrations/…` route's error names its new route. The loose topics now sit in Guides or Foundations instead of Unorganized, under the same names: `astryx docs getting-started` still opens, and its Up is `astryx docs guides`.
+
+@josephfarina
diff --git a/apps/docsite/scripts/docs-pages.mjs b/apps/docsite/scripts/docs-pages.mjs
index 36e70d88a8..40488798ea 100644
--- a/apps/docsite/scripts/docs-pages.mjs
+++ b/apps/docsite/scripts/docs-pages.mjs
@@ -25,44 +25,72 @@
export const GUIDE_PAGE_NAMESPACES = new Set(['cli']);
/**
- * The pages a root namespace in GUIDE_PAGE_NAMESPACES shows, as the docsite
- * listed them before the CLI's integration guide was split into short guides:
- * "CLI Integrations" and "Writing docs". Each is one full page of the
- * namespace at `route` (minus the routes in `except`, which another page
- * holds), at `slug`, so every guide slug below it redirects to its section
- * there. `aliases` are older slugs that redirect to the page.
+ * The pages a root namespace in GUIDE_PAGE_NAMESPACES shows besides one page
+ * per guide: each is one full page of the namespace at `route` (minus the
+ * routes in `except`, which another page holds), at `slug`, so every guide
+ * slug below it redirects to its section there. `aliases` are older slugs
+ * that redirect to the page. The integration guides that `cli` once held as
+ * two such pages now sit under `authoring`, an ordinary root namespace.
* @type {Map<string, Array<{route: string, slug: string, title: string, except?: string[], aliases?: string[]}>>}
*/
-export const GUIDE_NAMESPACE_PAGES = new Map([
- [
- 'cli',
- [
- {
- route: 'cli/integrations',
- slug: 'cli-integrations',
- title: 'CLI Integrations',
- except: ['cli/integrations/building-blocks/docs'],
- aliases: ['cli-integrations-overview'],
- },
- {
- route: 'cli/integrations/building-blocks/docs',
- slug: 'cli-writing-docs',
- title: 'Writing docs',
- aliases: ['cli-integrations-docs-add-a-topic'],
- },
- ],
- ],
-]);
+export const GUIDE_NAMESPACE_PAGES = new Map();
/**
* Older slugs of a root namespace's page, which redirect to it: global mode
- * was `cli/global`, and before that the `cli/install-once` guide.
+ * was `cli/global`, and before that the `cli/install-once` guide; the
+ * integration guides were the CLI Integrations page before `authoring` took
+ * them.
* @type {Map<string, string[]>}
*/
export const ROOT_PAGE_ALIASES = new Map([
['global', ['cli-global', 'cli-install-once']],
+ ['authoring', ['cli-integrations', 'cli-integrations-overview']],
+]);
+
+/**
+ * Older guide slugs of a root namespace, from before its guides moved there:
+ * the integration guides were `cli/integrations/…` (/docs/cli-integrations-…)
+ * before `authoring` took them, and the Writing docs page and one older alias
+ * pointed into them. Each opens where its guide's new slug does.
+ * @type {Map<string, {prefix: string, pages: Record<string, string>}>}
+ */
+export const MOVED_GUIDE_SLUGS = new Map([
+ [
+ 'authoring',
+ {
+ prefix: 'cli-integrations',
+ pages: {
+ 'cli-writing-docs': 'authoring-building-blocks-docs',
+ 'cli-integrations-docs-add-a-topic':
+ 'authoring-building-blocks-docs-add-a-topic',
+ },
+ },
+ ],
]);
+/**
+ * Redirects for a root namespace's older guide slugs (MOVED_GUIDE_SLUGS),
+ * read off the redirects its page made for the guides' new slugs.
+ * @param {string} root
+ * @param {Record<string, string>} redirects the page's redirects
+ * @returns {Record<string, string>}
+ */
+export function movedGuideRedirects(root, redirects) {
+ const moved = MOVED_GUIDE_SLUGS.get(root);
+ if (!moved) return {};
+ /** @type {Record<string, string>} */
+ const out = {};
+ for (const [slug, href] of Object.entries(redirects)) {
+ if (slug.startsWith(`${root}-`)) {
+ out[`${moved.prefix}-${slug.slice(root.length + 1)}`] = href;
+ }
+ }
+ for (const [old, now] of Object.entries(moved.pages)) {
+ if (Object.hasOwn(redirects, now)) out[old] = redirects[now];
+ }
+ return out;
+}
+
/**
* Flat topics whose full text the site shows on another topic's page. The
* theme split (before namespaces) left `theme` as a short overview and moved
@@ -188,8 +216,9 @@ export function namespaceCategory(own, guideCategories) {
* starts on the page. Typed docs (commands, API docs) open only in
* `astryx docs` and add nothing to the page.
*
- * A namespace with no guide placed under it (the tree's Unorganized level,
- * whose children are flat topics with pages of their own) has no page.
+ * A namespace with no guide placed under it (a generated topic level, Guides
+ * or Foundations, whose children are flat topics with pages of their own) has
+ * no page.
* @param {(topic?: string, section?: string, options?: object) => Promise<any>} readDocs
* @param {string} route
* @param {{slug?: string, title?: string, except?: string[], aliases?: string[]}} [options]
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index 8e59e3ccf2..aa738c4bb6 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -32,6 +32,7 @@ import {
GUIDE_NAMESPACE_PAGES,
GUIDE_PAGE_NAMESPACES,
ROOT_PAGE_ALIASES,
+ movedGuideRedirects,
mergeFlatTopics,
namespacePage,
routeSlug,
@@ -1769,7 +1770,11 @@ async function docsTreePages() {
});
if (!full) continue;
pages.push(full.page);
- Object.assign(redirects, full.redirects);
+ Object.assign(
+ redirects,
+ full.redirects,
+ movedGuideRedirects(root, full.redirects),
+ );
}
while (pending.length > 0) {
const route = pending.shift();
@@ -1890,7 +1895,7 @@ async function generateDocsRegistry() {
// slug (a former flat topic keeps its URL), and each guide under it
// redirects to its section there. Guides under GUIDE_PAGE_NAMESPACES keep a
// flat page whose slug is the route with "/" as "-", so
- // `cli/integrations/quick-start` is /docs/cli-integrations-quick-start.
+ // `cli/component-lookups` is /docs/cli-component-lookups.
const tree = await docsTreePages();
for (const page of tree.pages) {
if (docTopics.some(topic => topic.topic === page.topic)) {
diff --git a/apps/docsite/src/__tests__/docs-pages.test.ts b/apps/docsite/src/__tests__/docs-pages.test.ts
index 850be9b309..ea2f60359c 100644
--- a/apps/docsite/src/__tests__/docs-pages.test.ts
+++ b/apps/docsite/src/__tests__/docs-pages.test.ts
@@ -118,9 +118,9 @@ describe('a flat topic split into a docs-tree namespace', () => {
const read = async () => ({
type: 'docs.node',
data: {
- route: 'unorganized',
+ route: 'foundations',
kind: 'namespace',
- title: 'Unorganized',
+ title: 'Foundations',
content: [],
slots: [
{
@@ -130,7 +130,7 @@ describe('a flat topic split into a docs-tree namespace', () => {
],
},
});
- expect(await namespacePage(read, 'unorganized')).toBeNull();
+ expect(await namespacePage(read, 'foundations')).toBeNull();
});
});
@@ -298,8 +298,8 @@ describe('CLI commands on docsite pages', () => {
]);
});
- it('shows the CLI Integrations page a command that runs before any install', () => {
- const page = docTopics.find(topic => topic.topic === 'cli-integrations');
+ it('shows the Authoring page a command that runs before any install', () => {
+ const page = docTopics.find(topic => topic.topic === 'authoring');
const section = page?.sections.find(
each => each.title === 'Verify the packed import',
);
diff --git a/apps/docsite/src/__tests__/route-resolution.test.ts b/apps/docsite/src/__tests__/route-resolution.test.ts
index 2a0b571238..d030ff1dee 100644
--- a/apps/docsite/src/__tests__/route-resolution.test.ts
+++ b/apps/docsite/src/__tests__/route-resolution.test.ts
@@ -14,15 +14,14 @@ import {buildOutline} from '../components/docs/docOutline';
* Every topic page the site had before the CLI's docs were split into
* docs-tree namespaces, with its sidebar group. A split changes how agents
* read a topic, never where a reader finds it: each slug keeps one page in the
- * same group. The CLI's integration guides were split earlier, from the CLI
- * Integrations and Writing docs pages; those two pages are back too.
+ * same group. The CLI Integrations and Writing docs pages are the exception:
+ * their guides moved under Authoring, the one home for integration authors,
+ * so their slugs redirect into the Authoring page (tested below).
*/
const PAGES_BEFORE_THE_SPLITS: Record<string, 'guide' | 'foundations'> = {
authoring: 'guide',
'browser-support': 'guide',
'cli-component-lookups': 'guide',
- 'cli-integrations': 'guide',
- 'cli-writing-docs': 'guide',
color: 'foundations',
elevation: 'foundations',
'getting-started': 'guide',
@@ -92,7 +91,7 @@ describe('route resolution', () => {
// The Guide section as it was before the CLI integration guide and the
// other topics were split into short guides. `styling-overview` and
// `cli-host-entry` are topics added since; `global` is the Global mode
- // page.
+ // page; `authoring` holds what CLI Integrations and Writing docs did.
const sidebarGuides = docTopics
.filter(d => d.category === 'guide' && d.topic !== 'getting-started')
.map(d => d.topic)
@@ -103,8 +102,6 @@ describe('route resolution', () => {
'browser-support',
'cli-component-lookups',
'cli-host-entry',
- 'cli-integrations',
- 'cli-writing-docs',
'global',
'internationalization',
'is-my-code-good',
@@ -120,18 +117,30 @@ describe('route resolution', () => {
);
});
- it('opens every CLI integration guide at its section on a full page', () => {
+ it('opens every authoring guide at its section on the Authoring page, from its old slug too', () => {
+ expect(pageBySlug.get('authoring')?.category).toBe('guide');
+ let guides = 0;
for (const route of docsTreeRoutes) {
- if (!route.startsWith('cli/integrations/')) continue;
+ if (!route.startsWith('authoring/')) {continue;}
+ guides++;
const slug = route.replaceAll('/', '-');
expect(pageBySlug.has(slug), slug).toBe(false);
- expect(docRedirects[slug], slug).toMatch(
- /^\/docs\/cli-(integrations|writing-docs)(#|$)/,
- );
+ expect(docRedirects[slug], slug).toMatch(/^\/docs\/authoring(#|$)/);
+ // The guide's slug from when it sat under cli/integrations.
+ const old = `cli-integrations-${slug.slice('authoring-'.length)}`;
+ expect(pageBySlug.has(old), old).toBe(false);
+ expect(docRedirects[old], old).toBe(docRedirects[slug]);
+ }
+ expect(guides).toBeGreaterThan(40);
+ for (const old of ['cli-integrations', 'cli-integrations-overview']) {
+ expect(pageBySlug.has(old), old).toBe(false);
+ expect(docRedirects[old], old).toBe('/docs/authoring');
}
- expect(docRedirects['cli-integrations-overview']).toBe(
- '/docs/cli-integrations',
+ expect(pageBySlug.has('cli-writing-docs')).toBe(false);
+ expect(docRedirects['cli-writing-docs']).toBe(
+ docRedirects['authoring-building-blocks-docs'],
);
+ expect(docRedirects['cli-writing-docs']).toMatch(/^\/docs\/authoring#/);
});
it('shows global mode as one page under Guide, with its older slugs redirecting to it', () => {
@@ -141,7 +150,7 @@ describe('route resolution', () => {
expect(docRedirects['cli-global']).toBe('/docs/global');
expect(docRedirects['cli-install-once']).toBe('/docs/global');
for (const route of docsTreeRoutes) {
- if (!route.startsWith('global/')) continue;
+ if (!route.startsWith('global/')) {continue;}
const slug = route.replaceAll('/', '-');
expect(docRedirects[slug], slug).toMatch(/^\/docs\/global#/);
}
diff --git a/apps/docsite/src/components/codeLinkifiers.ts b/apps/docsite/src/components/codeLinkifiers.ts
index ddf52f1919..c3d54e2522 100644
--- a/apps/docsite/src/components/codeLinkifiers.ts
+++ b/apps/docsite/src/components/codeLinkifiers.ts
@@ -47,7 +47,7 @@ const docTopic: CodeLinkifier = code => {
return '/docs';
}
// A docs-tree guide has a slug named after its route, with "/" as "-": its
- // own page (`cli/integrations/quick-start`), or a redirect to its section on
+ // own page (`authoring/quick-start`), or a redirect to its section on
// its namespace's page (`layout/scaffold` -> /docs/layout#scaffold).
const slug = topic.replaceAll('/', '-');
if (KNOWN_TOPICS.has(slug)) {
diff --git a/docs/architecture/cli-surface.md b/docs/architecture/cli-surface.md
index bdbe193c75..42e2473162 100644
--- a/docs/architecture/cli-surface.md
+++ b/docs/architecture/cli-surface.md
@@ -487,8 +487,9 @@ validate` MUST warn on a PascalCase `.tsx` at the top of the components root
- **INV25 — Every CLI doc names the group that reads it.** Each command, API
function, schema, and enum doc the CLI ships declares a `namespace`. The docs
tree adopts `cli/commands` and `cli/api` docs, one route each under
- `cli/commands` and `cli/api/<kind>s`; `authoring` docs are sections of
- `astryx docs authoring` and appear in its list. `astryx doctor` fails when a
+ `cli/commands` and `cli/api/<kind>s`; `authoring` docs are sections of the
+ field reference, `astryx docs authoring/field-reference`, and appear in its
+ list; `astryx docs authoring <name>` reads one. `astryx doctor` fails when a
CLI doc has no namespace, names one nothing reads, or disagrees with the
authoring list, so every doc the CLI ships stays readable from the CLI.
- **INV26 — The docs tree gives each doc one home (`spec:AST-046`).** The tree
@@ -499,8 +500,9 @@ validate` MUST warn on a PascalCase `.tsx` at the top of the components root
on any tree error diagnostic or unplaced CLI doc.
An integration's namespace docs and placed guides join the same tree, named
by its provider id; the CLI's own docs keep a contested route.
- Every flat topic sits in the generated Unorganized level under its own name,
- so every doc has a home in the tree.
+ Every flat topic sits in the generated level for its category, Guides or
+ Foundations, under its own name, so every doc has a named home in the tree.
+ Everything an integration author reads lives under `authoring`.
- **INV27 — Every read says where to go next (`spec:AST-047`).** A read names
its place and ends with its moves (up, down, across, and out) as runnable
commands, and its JSON carries the same moves as `links`; a search hit
@@ -819,37 +821,37 @@ workspace member then migrates against a Core its workspace does not use).
## Verification
-| Invariant | Evidence | Failure signal |
-| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| INV1 | `clients/cli/commands/interactive-guard.test.mjs` | The subprocess hangs: `signal === 'SIGTERM'` and `status === null`. |
-| INV2 | `clients/cli/commands/json-contract.test.mjs` | `--json` stdout does not parse, or parses to a shape outside the two. |
-| INV3 | `foundation/response/error-codes.test.mjs` | A shipped code disappears, or an envelope carries an unregistered one. |
-| INV4 | `clients/cli/formatters/index.test.mjs`, type tests | `emit` accepts a bare string, or output varies between pipe and TTY. |
-| INV6 | `pnpm check:cli-structure` | A command's file or its doc is missing, or sits at the wrong path. |
-| INV8 | `clients/cli/cli-exit-codes.test.mjs` | The same condition exits differently with and without `--json`. |
-| INV10b | `api/upgrade/run/run.test.mjs` (a folder that installs Core without declaring it upgrades the project above it; a member its workspace lists and one that declares Astryx keep their own), `clients/cli/commands/upgrade.subfolder-path.test.mjs` | A folder that installs Core without declaring Astryx upgrades only itself, or a declaring folder or a listed member upgrades the project above it. |
-| INV14 | `foundation/integrations/autolink.test.mjs`, `foundation/config/project.test.mjs` | An undeclared package contributes, or configured/local precedence changes. |
-| INV15 | `api/integration/add-contribution.test.mjs`, `clients/cli/commands/integration-authoring.test.mjs` | Dry-run/write paths differ, a writer clobbers bytes, or the new contribution is not discoverable. |
-| INV16 | `foundation/integrations/manifest-writer.test.mjs`, `api/integration/add-contribution.test.mjs` | A writer invents package policy, replaces an author entry, or local bytes lose precedence. |
-| INV17 | `api/integration/pack-check.test.mjs` | Lifecycle output, packed files, identities, or public imports diverge without failing the gate. |
-| INV18 | `api/integration/validate-integration.test.mjs`, `api/theme/integration-themes.test.mjs` | Diagnostics mutate files, or a selected broken theme package is reported as merely unknown. |
-| INV19 | `clients/cli/commands/integration-real-world.test.mjs` | A CLI-authored theme, nested palette, or guides fail across pack, install, list, add, and build. |
-| INV20 | `pnpm check:cli-structure` checks that each subject has a `FunctionDoc`, typedefs, and a test; per-function coverage and leaf layout are checked in review | A subject or exported function lacks its `FunctionDoc`, typedefs, or tests, or an operation sits outside its subject. |
-| INV21 | Review of imports under `api/**`; no mechanical check yet | A module other than a subject's adapter reads or writes files, contacts the network, starts a subprocess, loads the project, or runs discovery. |
-| INV22 | Review of imports under `clients/cli/commands/**`; the docs drift harness checks each `CommandDoc` against the live command | A handler reaches the environment itself, an executable command's `CommandDoc` names no `fn`, or a non-command file sits in the directory. |
-| INV23 | `clients/cli/formatters/index.test.mjs` for the kit; review of handlers; no mechanical check yet | A handler pads, aligns, or draws text itself, or a block kind is missing from the help "Output format" list. |
-| INV24 | `api/integration/add-contribution.test.mjs`, `api/integration/add-theme.test.mjs`, `foundation/discovery/theme-discovery.test.mjs` | New authoring emits an untyped or non-`.doc.mjs` item, adding one item edits a shared file, or an item catalog becomes authoritative. |
-| INV25 | `foundation/discovery/cli-self-docs.test.mjs`, `api/doctor/doctor.test.mjs` | A CLI doc with no namespace, a namespace no topic reads, or no section in its topic passes doctor. |
-| INV28 | `test/inv28-package-provenance.test.mjs`, `clients/cli/commands/text-json-parity.test.mjs`, `cli-api-types-verify` | A result about one artifact has no envelope `package`, a listed artifact has no `package`, or text omits the package the envelope names. |
-| INV29 | `api/doctor/doctor.test.mjs` (configured-integrations: not installed, no manifest, manifest throws; self-named authored package, direct and through a symlinked `node_modules` or `cwd`; provider-conflict set-aside; an astryx.config that imports but cannot load the project → failed `config` check) | A configured integration that cannot load leaves `doctor` at exit 0, or an installed-but-unnamed one fails it |
-| INV30 | `foundation/runtime/package-set.test.mjs`, `foundation/runtime/hosted-runtime.test.mjs` | A run resolves from two roots; a root contributes an integration inside a project, including an `@astryxdesign/*` package that ships an integration manifest; a run the starting copy answers resolves from a root other than the one that holds it, or is announced as a fallback when that copy is the release `spec:AST-081` FR2 names; a run another named release answers resolves from a root whose CLI is not that release, from one that lacks a version the project would install, or from a later root when an earlier one qualifies; a hosted run installs a release, or a named-release run with no qualifying root does not fall back as FR2 says; a lookup consults a root before the project's own install, or with no set active; an approved integration resolves from another root or skips its validation; a root's config is read; a run writes into a package root or outside the places `spec:AST-081` FR7 names; the host entry's result lacks a resolved package or its source; or a project check judges the package set. |
-| INV31 | `foundation/agent-docs/agent-docs.test.mjs`, `foundation/agent-docs/agent-docs.path-safety.test.mjs`, `clients/cli/commands/init.behavior.test.mjs`, `api/init/remove/remove.test.mjs`, `clients/cli/commands/doctor.test.mjs` | A layout test finds the block missing from a file INV31 names or present in a file it excludes, a managed import of a block-less `AGENTS.md` passes doctor, agent docs land in the home folder or in a settings folder outside a project, or `--remove-agents` leaves a block at the project root or in the working folder. |
-| INV32 | `test/cli-strict-guard.test.mjs` lists every command offering `--strict` and every command whose exit depends on warnings; `api/integration/check/check.test.mjs` compares a strict run with the default run | A second command offers `--strict`, a command exits 1 on a warning alone without `--strict`, or a strict run reports a finding the default run does not or outside the command's issue format. |
-| INV33 | `foundation/discovery/prop-drift.test.mjs`, `foundation/discovery/doc-consistency.test.mjs`, `foundation/discovery/type-text.test.mjs`, `clients/cli/commands/doctor-integration.test.mjs`, `test/core-prop-docs.test.mjs` | A removed or renamed prop or a changed union passes unreported, a missing compiler reads as a pass, or a table that leaves out `ref`, `key`, `xstyle`, `className`, `style`, `data-testid`, or an `@internal` prop draws a warning. |
-| INV34 | `foundation/discovery/doc-types.test.mjs`, `foundation/discovery/doc-consistency.test.mjs`, `clients/cli/commands/doctor-integration.test.mjs`, `test/core-doc-types.test.mjs` | An unknown, missing, or mistyped field passes unreported, or a missing compiler reads as a pass. |
+| Invariant | Evidence | Failure signal |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| INV1 | `clients/cli/commands/interactive-guard.test.mjs` | The subprocess hangs: `signal === 'SIGTERM'` and `status === null`. |
+| INV2 | `clients/cli/commands/json-contract.test.mjs` | `--json` stdout does not parse, or parses to a shape outside the two. |
+| INV3 | `foundation/response/error-codes.test.mjs` | A shipped code disappears, or an envelope carries an unregistered one. |
+| INV4 | `clients/cli/formatters/index.test.mjs`, type tests | `emit` accepts a bare string, or output varies between pipe and TTY. |
+| INV6 | `pnpm check:cli-structure` | A command's file or its doc is missing, or sits at the wrong path. |
+| INV8 | `clients/cli/cli-exit-codes.test.mjs` | The same condition exits differently with and without `--json`. |
+| INV10b | `api/upgrade/run/run.test.mjs` (a folder that installs Core without declaring it upgrades the project above it; a member its workspace lists and one that declares Astryx keep their own), `clients/cli/commands/upgrade.subfolder-path.test.mjs` | A folder that installs Core without declaring Astryx upgrades only itself, or a declaring folder or a listed member upgrades the project above it. |
+| INV14 | `foundation/integrations/autolink.test.mjs`, `foundation/config/project.test.mjs` | An undeclared package contributes, or configured/local precedence changes. |
+| INV15 | `api/integration/add-contribution.test.mjs`, `clients/cli/commands/integration-authoring.test.mjs` | Dry-run/write paths differ, a writer clobbers bytes, or the new contribution is not discoverable. |
+| INV16 | `foundation/integrations/manifest-writer.test.mjs`, `api/integration/add-contribution.test.mjs` | A writer invents package policy, replaces an author entry, or local bytes lose precedence. |
+| INV17 | `api/integration/pack-check.test.mjs` | Lifecycle output, packed files, identities, or public imports diverge without failing the gate. |
+| INV18 | `api/integration/validate-integration.test.mjs`, `api/theme/integration-themes.test.mjs` | Diagnostics mutate files, or a selected broken theme package is reported as merely unknown. |
+| INV19 | `clients/cli/commands/integration-real-world.test.mjs` | A CLI-authored theme, nested palette, or guides fail across pack, install, list, add, and build. |
+| INV20 | `pnpm check:cli-structure` checks that each subject has a `FunctionDoc`, typedefs, and a test; per-function coverage and leaf layout are checked in review | A subject or exported function lacks its `FunctionDoc`, typedefs, or tests, or an operation sits outside its subject. |
+| INV21 | Review of imports under `api/**`; no mechanical check yet | A module other than a subject's adapter reads or writes files, contacts the network, starts a subprocess, loads the project, or runs discovery. |
+| INV22 | Review of imports under `clients/cli/commands/**`; the docs drift harness checks each `CommandDoc` against the live command | A handler reaches the environment itself, an executable command's `CommandDoc` names no `fn`, or a non-command file sits in the directory. |
+| INV23 | `clients/cli/formatters/index.test.mjs` for the kit; review of handlers; no mechanical check yet | A handler pads, aligns, or draws text itself, or a block kind is missing from the help "Output format" list. |
+| INV24 | `api/integration/add-contribution.test.mjs`, `api/integration/add-theme.test.mjs`, `foundation/discovery/theme-discovery.test.mjs` | New authoring emits an untyped or non-`.doc.mjs` item, adding one item edits a shared file, or an item catalog becomes authoritative. |
+| INV25 | `foundation/discovery/cli-self-docs.test.mjs`, `api/doctor/doctor.test.mjs` | A CLI doc with no namespace, a namespace no topic reads, or no section in its topic passes doctor. |
+| INV28 | `test/inv28-package-provenance.test.mjs`, `clients/cli/commands/text-json-parity.test.mjs`, `cli-api-types-verify` | A result about one artifact has no envelope `package`, a listed artifact has no `package`, or text omits the package the envelope names. |
+| INV29 | `api/doctor/doctor.test.mjs` (configured-integrations: not installed, no manifest, manifest throws; self-named authored package, direct and through a symlinked `node_modules` or `cwd`; provider-conflict set-aside; an astryx.config that imports but cannot load the project → failed `config` check) | A configured integration that cannot load leaves `doctor` at exit 0, or an installed-but-unnamed one fails it |
+| INV30 | `foundation/runtime/package-set.test.mjs`, `foundation/runtime/hosted-runtime.test.mjs` | A run resolves from two roots; a root contributes an integration inside a project, including an `@astryxdesign/*` package that ships an integration manifest; a run the starting copy answers resolves from a root other than the one that holds it, or is announced as a fallback when that copy is the release `spec:AST-081` FR2 names; a run another named release answers resolves from a root whose CLI is not that release, from one that lacks a version the project would install, or from a later root when an earlier one qualifies; a hosted run installs a release, or a named-release run with no qualifying root does not fall back as FR2 says; a lookup consults a root before the project's own install, or with no set active; an approved integration resolves from another root or skips its validation; a root's config is read; a run writes into a package root or outside the places `spec:AST-081` FR7 names; the host entry's result lacks a resolved package or its source; or a project check judges the package set. |
+| INV31 | `foundation/agent-docs/agent-docs.test.mjs`, `foundation/agent-docs/agent-docs.path-safety.test.mjs`, `clients/cli/commands/init.behavior.test.mjs`, `api/init/remove/remove.test.mjs`, `clients/cli/commands/doctor.test.mjs` | A layout test finds the block missing from a file INV31 names or present in a file it excludes, a managed import of a block-less `AGENTS.md` passes doctor, agent docs land in the home folder or in a settings folder outside a project, or `--remove-agents` leaves a block at the project root or in the working folder. |
+| INV32 | `test/cli-strict-guard.test.mjs` lists every command offering `--strict` and every command whose exit depends on warnings; `api/integration/check/check.test.mjs` compares a strict run with the default run | A second command offers `--strict`, a command exits 1 on a warning alone without `--strict`, or a strict run reports a finding the default run does not or outside the command's issue format. |
+| INV33 | `foundation/discovery/prop-drift.test.mjs`, `foundation/discovery/doc-consistency.test.mjs`, `foundation/discovery/type-text.test.mjs`, `clients/cli/commands/doctor-integration.test.mjs`, `test/core-prop-docs.test.mjs` | A removed or renamed prop or a changed union passes unreported, a missing compiler reads as a pass, or a table that leaves out `ref`, `key`, `xstyle`, `className`, `style`, `data-testid`, or an `@internal` prop draws a warning. |
+| INV34 | `foundation/discovery/doc-types.test.mjs`, `foundation/discovery/doc-consistency.test.mjs`, `clients/cli/commands/doctor-integration.test.mjs`, `test/core-doc-types.test.mjs` | An unknown, missing, or mistyped field passes unreported, or a missing compiler reads as a pass. |
| INV35 | `api/integration/check/check.test.mjs`, `clients/cli/commands/integration-check.test.mjs`, `test/integration-check-failures.test.mjs`, `api/search/search.integration-check.test.mjs`, `foundation/discovery/prop-drift.test.mjs`, `foundation/discovery/type-match.test.mjs`, `foundation/discovery/doc-types.test.mjs`, `api/integration/authoring-checks.test.mjs`, `foundation/discovery/stray-pointers.test.mjs` | The default exit differs from a check's own, a warning or a skipped comparison passes `--strict`, text and JSON exit differently, a new failing finding is added without the list changing, a search for ci does not find the command first, a finding is reported on a doc the code does not contradict (for a type, one TypeScript accepts), or a copied passage or a fluff finding passes `--strict`, or a function-word run or shared boilerplate is reported as a copy. |
-| INV36 | `api/gap-report/gap-report.test.mjs`, `clients/cli/commands/gap-report.test.mjs` | A run without `--to` reaches an `issuesUrl` the handlers did not choose, `--to` runs a handler or files on GitHub without `--confirm-public`, an unknown `--to` sends anything, or the destinations list or its line telling the agent to ask the person is missing while a destination exists. |
-| INV37 | `api/integration/validate-integration.test.mjs`, `api/integration/validate-integration-fixes.test.mjs`, `api/integration/pack-check.test.mjs` | A top-level source with no doc passes `--strict` (a dotted template id such as `landing.page` included), or a test, spec or story file or a subfolder helper is flagged. |
+| INV36 | `api/gap-report/gap-report.test.mjs`, `clients/cli/commands/gap-report.test.mjs` | A run without `--to` reaches an `issuesUrl` the handlers did not choose, `--to` runs a handler or files on GitHub without `--confirm-public`, an unknown `--to` sends anything, or the destinations list or its line telling the agent to ask the person is missing while a destination exists. |
+| INV37 | `api/integration/validate-integration.test.mjs`, `api/integration/validate-integration-fixes.test.mjs`, `api/integration/pack-check.test.mjs` | A top-level source with no doc passes `--strict` (a dotted template id such as `landing.page` included), or a test, spec or story file or a subfolder helper is flagged. |
## Open questions
diff --git a/docs/architecture/template-authoring.md b/docs/architecture/template-authoring.md
index a773d823e5..daef990e07 100644
--- a/docs/architecture/template-authoring.md
+++ b/docs/architecture/template-authoring.md
@@ -170,7 +170,7 @@ authoring check; it does not replace runtime catalog validation.
This record does not absorb adjacent facts:
-- The shipped `cli/integrations/templates/template-quality` guide owns the public
+- The shipped `authoring/building-blocks/templates/write-good-templates` guides own the public
grading rules, rubric version, grade bands, categories, weights, and agent
workflow. The public
[Contributing Templates](https://github.com/facebook/astryx/wiki/Contributing-Templates)
diff --git a/docs/specs/AST-031/spec.md b/docs/specs/AST-031/spec.md
index 881db800c5..b26eca0381 100644
--- a/docs/specs/AST-031/spec.md
+++ b/docs/specs/AST-031/spec.md
@@ -13,7 +13,7 @@ owners: [josephfarina, cixzhang]
affects_architecture: [architecture:cli-surface]
affects_families: []
affects_contributing: []
-affects_consumer_docs: [cli/integrations]
+affects_consumer_docs: [authoring]
---
# Runtime integration feature composition system spec
diff --git a/docs/specs/AST-035/spec.md b/docs/specs/AST-035/spec.md
index bd07825f7f..58b0c4868c 100644
--- a/docs/specs/AST-035/spec.md
+++ b/docs/specs/AST-035/spec.md
@@ -13,7 +13,7 @@ owners: [josephfarina, cixzhang]
affects_architecture: [architecture:cli-surface]
affects_families: []
affects_contributing: [contributing:templates, contributing:api-conventions]
-affects_consumer_docs: [cli/integrations]
+affects_consumer_docs: [authoring]
---
# Integration template and component replacement system spec
diff --git a/docs/specs/AST-039/spec.md b/docs/specs/AST-039/spec.md
index 5807589e98..056c8c76d7 100644
--- a/docs/specs/AST-039/spec.md
+++ b/docs/specs/AST-039/spec.md
@@ -13,7 +13,7 @@ owners: [josephfarina]
affects_architecture: [architecture:cli-surface]
affects_families: []
affects_contributing: [contributing:cli-conventions]
-affects_consumer_docs: [cli/integrations]
+affects_consumer_docs: [authoring]
---
# Integration contribution descriptor system spec
diff --git a/docs/specs/AST-040-consumer-file-modification/spec.md b/docs/specs/AST-040-consumer-file-modification/spec.md
index 14244942bf..9ff5868e70 100644
--- a/docs/specs/AST-040-consumer-file-modification/spec.md
+++ b/docs/specs/AST-040-consumer-file-modification/spec.md
@@ -13,7 +13,7 @@ owners: [josephfarina]
affects_architecture: [architecture:cli-surface]
affects_families: []
affects_contributing: [contributing:cli-conventions]
-affects_consumer_docs: [cli/integrations]
+affects_consumer_docs: [authoring]
---
# Evidence-based consumer file modification system spec
@@ -193,7 +193,7 @@ permission to edit matching literals anywhere in that file. Both behaviors are
non-conforming with FR1–FR3; this record does not choose their implementation.
Post-codemod hooks already exist and serve as the declared regeneration for FR5.
-The `cli/integrations` guide and the codemod authoring guidance must
+The `authoring` guides and the codemod authoring guidance must
explain protection, how to mark generated files, and how transforms prove scope.
This specification-only change alters no runtime behavior or published package
diff --git a/docs/specs/AST-046-docs-tree/spec.md b/docs/specs/AST-046-docs-tree/spec.md
index 3b82b5cf0a..3a549a0660 100644
--- a/docs/specs/AST-046-docs-tree/spec.md
+++ b/docs/specs/AST-046-docs-tree/spec.md
@@ -7,13 +7,13 @@ authority: current
archive_reason: null
superseded_by: null
approved_by: josephfarina
-approved_at: 2026-10-08
+approved_at: 2026-10-21
phase: implementing
owners: [josephfarina]
affects_architecture: [architecture:cli-surface]
affects_families: []
affects_contributing: []
-affects_consumer_docs: [cli/integrations, authoring]
+affects_consumer_docs: [authoring, guides, foundations]
---
# Documentation tree system spec
@@ -42,7 +42,8 @@ This record owns how a doc gets its one home in the tree, how a route is formed,
how `astryx docs` reads the tree, and what `astryx doctor` checks. It rolls out
in phases: phase 1 places the CLI's own docs and the namespace docs and guides
each integration ships, and gives every other doc a home in a generated
-Unorganized level; later phases move those docs into real sections.
+level named for its category, Guides or Foundations; later phases may move
+those docs into real sections.
A long flat topic can become a namespace of short guides, so a reader loads only
the guide that answers. The split keeps the unambiguous reads a released
@@ -80,7 +81,7 @@ and references from other packages are an open question (OQ2).
- **FR2 — Each doc has one home, decided in a fixed order.** A doc's home MUST
be decided once, in this order: its explicit `placement`; otherwise the one
adoption rule in its own package that matches its discovery group and kind;
- otherwise, for a reference topic, the generated Unorganized level (FR12). A placement MUST name a namespace of the doc's own package
+ otherwise, for a reference topic, the generated level for its category (FR12). A placement MUST name a namespace of the doc's own package
(`namespace:<name>`), a slot that namespace declares, and a slot that accepts
the doc's kind. A placement that fails MUST withdraw the doc with a
diagnostic; it MUST NOT fall back to adoption. A doc that two rules adopt MUST
@@ -141,12 +142,15 @@ and references from other packages are an open question (OQ2).
checks warn, so a project that passed without them keeps passing. The progressive-disclosure check MUST hold each guide the tree
places to the same size budget as every topic.
- **FR9 — Phase 1 places the CLI's own docs.** The CLI MUST ship the `cli`
- namespace with the `integrations` namespace and the `commands` and `api`
- namespaces under it. Every command doc MUST have a route under
- `cli/commands`, and every function, schema, and enum doc in the `cli/api`
- group a route under `cli/api/<kind>s`. The integration guides MUST live under
- `cli/integrations`, one short guide per task, and no flat topic is named
- `cli-integrations`. Under `spec:AST-017/FR45`, a CLI route or name MAY
+ namespace with the `commands` and `api` namespaces under it, and the
+ `authoring` namespace, the one home for integration authors. Every command
+ doc MUST have a route under `cli/commands`, and every function, schema, and
+ enum doc in the `cli/api` group a route under `cli/api/<kind>s`. The
+ integration guides MUST live under `authoring`, one short guide per task,
+ beside the field reference whose sections `astryx docs authoring <name>`
+ reads, and no flat topic is named `cli-integrations` or `authoring`. An old
+ `cli/integrations` route MUST stay unknown, and its not-found error MUST name
+ the guide's new route under `authoring`. Under `spec:AST-017/FR45`, a CLI route or name MAY
change like this when every reference changes with it: links name docs by
identity (`spec:AST-047` FR9), and the graph walk fails on a reference
left behind (`spec:AST-047` FR11, FR12).
@@ -165,7 +169,7 @@ and references from other packages are an open question (OQ2).
provider id (FR1) and name its `package` by the integration's npm name, and
hold them to FR2–FR8. A placed guide MUST NOT also `replaces` or `extends` a
topic. When two providers claim one route, the CLI's own docs MUST keep it,
- including its flat topics' names and the Unorganized level, then integrations
+ including its flat topics' names and the generated topic levels, then integrations
in configured order; between integrations a namespace keeps its route over a
topic, and a name a topic answers to through `replaces` is that topic's route.
The claim that loses MUST be a `duplicate_route` diagnostic filed against the
@@ -185,13 +189,17 @@ and references from other packages are an open question (OQ2).
covers a template that sets `replaces` (`spec:AST-035`), a doc section that
sets `id`, and a theme, whose typed descriptor an older CLI rejects along
with the package's doc topics; `integration add theme` declares the peer.
-- **FR12 — Every doc has a home.** Every flat topic, the CLI's and each
- integration's, MUST sit in the generated Unorganized level (`unorganized`), in
- the order the topic list reads. The level has no authored doc, so its `id` is
- `null`, and it lists its topics one level down with the command that opens
- each. A topic keeps its own name as its route, so no name changes; a read of
- it offers Up to the level and Previous and Next among its topics, as any tree
- node does. Placing a topic in a real section takes it out of the level.
+- **FR12 — Every doc has a named home.** Every flat topic, the CLI's and
+ each integration's, MUST sit in the generated level for its category, in the
+ order the topic list reads: `foundations` (Foundations) for a foundations
+ topic, and `guides` (Guides) for any other. A level has no authored doc, so
+ its `id` is `null`, and it lists its topics one level down with the command
+ that opens each. A topic keeps its own name as its route, so no name
+ changes; a read of it offers Up to its level and Previous and Next among its
+ level's topics, as any tree node does. Placing a topic in a real section
+ takes it out of its level. Every flat topic the CLI ships MUST declare the
+ `guide` or `foundations` category, and the repository's tests MUST fail on
+ one that does not.
- **FR13 — A flat topic becomes a namespace without breaking an unambiguous
read.** A
provider's flat topic MAY become a namespace of guides only when every rule
@@ -202,9 +210,12 @@ and references from other packages are an open question (OQ2).
- Every section of the topic lands in exactly one guide, with its title, its
`id`, and the key a reader addresses it by unchanged; when regrouping would
change a section's derived key, the section's `id` pins the old key. No
- section is dropped, merged into another, or copied into two guides. No two
- guides below the namespace share a section key, so a section read names one
- guide (FR6).
+ section is dropped, merged into another, or copied into two guides. No
+ guide below the namespace shares a key with one of the topic's own
+ sections, so every section read that worked on the topic still names one
+ guide (FR6). Guides placed below the namespace from elsewhere MAY share
+ other keys with each other; a namespace read of such a key fails as FR6
+ states and names those guides.
- Each guide answers one task or one decision a reader brings, and its title
and summary name it. A guide is not a fragment cut at a size, and each
meets the size budget of FR8.
@@ -234,7 +245,7 @@ and references from other packages are an open question (OQ2).
at the guide's slug, and has no namespace page. A namespace page's sidebar
group MUST be the namespace's own `category`; without one, `foundations`
when every guide below it is a foundations doc, and `guide` otherwise. A
- namespace with no guide below it, such as the Unorganized level (FR12), has
+ namespace with no guide below it, such as a generated topic level (FR12), has
no page. The docsite build MUST fail when a slug is both a page and a
redirect, or both a flat topic and a namespace page.
@@ -263,30 +274,35 @@ Phase 1 changes these surfaces:
`astryx doctor integration docs` checks them, as FR11 states;
- `cli-integrations` moves to `cli/integrations`, and every reference moves
with it;
-- every flat topic sits in the generated Unorganized level, as FR12 states;
+- the integration guides then move from `cli/integrations` to `authoring`,
+ beside the field reference, and every reference moves with them; an old
+ route's not-found error names its new one (FR9);
+- every flat topic sits in the generated level for its category, Guides or
+ Foundations, as FR12 states;
- a flat topic that becomes a namespace keeps its unambiguous reads inside
its own package, as FR13 and FR6 state;
- the docsite reads the tree through `docs()`: each root namespace is one page
and its guides' slugs redirect into it (FR14); the `cli` namespace's guides
- keep their own pages, and `/docs/cli-integrations` redirects to the first of
- them.
+ keep their own pages, and `/docs/cli-integrations`, every
+ `/docs/cli-integrations-…` guide slug, and `/docs/cli-writing-docs` redirect
+ into `/docs/authoring`.
`architecture:cli-surface` INV25 and INV26 carry this record into the code.
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| ------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1, FR3, FR4 | Tree builder fixture tests | three authored levels; adoption with and without `groupBy`; reversed input order; order and title sort | A route that ignores the parent, a folder that implies a parent, or a tree that depends on input order |
-| FR2 | Tree builder failure fixtures | no slot; unknown slot; a slot that refuses the kind; another package's parent; not a reference; two adopters; a cycle | A failed placement that falls back to adoption, or a failure without a diagnostic |
-| FR5, FR6, FR7 | `docs()` dispatcher tests and CLI runs | `cli`, `cli/api`, one function, the placed guide and its sections, the old name, a typo route; a section on a namespace that one guide, no guide, and two guides hold | A namespace that inlines grandchildren, a lost section read, a section read that picks one of two guides, or a wrong error code |
-| FR8 | Doctor tests | this repo; a fixture tree with a broken placement | A broken tree or an unplaced CLI doc that passes |
-| FR9 | Real-tree tests and the route inventory | every command, function, schema, and enum doc; every exported API function | A CLI typed doc without its route, or a route inventory row the tree contradicts |
-| FR10 | Search tests and CLI runs | a guide section; a typed doc by its own name; an error code; a topic hit; no core installed | A section hit whose command reads the whole topic, or a docs-only search that needs core |
-| FR11 | Integration tree tests | a namespace and two placed guides from a package whose provider id differs from its name; a broken link; a claim on the `cli` route | A node named by the package name, a broken link that passes either doctor, or an integration that takes a CLI route |
-| FR12 | `docs()` tests, the graph walk, and search tests | the level and its children in list order; a topic's Up, Previous, and Next; a flat topic hit's parent; an integration's flat topic | A flat topic without a home, a topic whose name changes, or a level that lists a placed guide |
-| FR13 | Split tests over the topic before and after, the graph walk, and search tests | each old section key read through the namespace; a link and a token reference to the old topic; a `--dense` read; the topic list and a search for one section | A dropped, merged, or copied section; a changed title or `id`; a reference left on the old identity; a name listed twice; a section found twice |
-| FR14 | Docsite page-generation and route-resolution tests | a split namespace; a nested namespace; a package-page namespace; a namespace with a `category`, and one whose guides are all foundations docs; the Unorganized level | An old address that stops resolving or lands in another sidebar group, a permanent guide redirect, a guide page on a non-package namespace, or a slug that is both a page and a redirect |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| ------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1, FR3, FR4 | Tree builder fixture tests | three authored levels; adoption with and without `groupBy`; reversed input order; order and title sort | A route that ignores the parent, a folder that implies a parent, or a tree that depends on input order |
+| FR2 | Tree builder failure fixtures | no slot; unknown slot; a slot that refuses the kind; another package's parent; not a reference; two adopters; a cycle | A failed placement that falls back to adoption, or a failure without a diagnostic |
+| FR5, FR6, FR7 | `docs()` dispatcher tests and CLI runs | `cli`, `cli/api`, one function, the placed guide and its sections, the old name, a typo route; a section on a namespace that one guide, no guide, and two guides hold | A namespace that inlines grandchildren, a lost section read, a section read that picks one of two guides, or a wrong error code |
+| FR8 | Doctor tests | this repo; a fixture tree with a broken placement | A broken tree or an unplaced CLI doc that passes |
+| FR9 | Real-tree tests and the route inventory | every command, function, schema, and enum doc; every exported API function | A CLI typed doc without its route, or a route inventory row the tree contradicts |
+| FR10 | Search tests and CLI runs | a guide section; a typed doc by its own name; an error code; a topic hit; no core installed | A section hit whose command reads the whole topic, or a docs-only search that needs core |
+| FR11 | Integration tree tests | a namespace and two placed guides from a package whose provider id differs from its name; a broken link; a claim on the `cli` route | A node named by the package name, a broken link that passes either doctor, or an integration that takes a CLI route |
+| FR12 | `docs()` tests, the graph walk, and search tests | the level and its children in list order; a topic's Up, Previous, and Next; a flat topic hit's parent; an integration's flat topic | A flat topic without a home, a topic whose name changes, or a level that lists a placed guide |
+| FR13 | Split tests over the topic before and after, the graph walk, and search tests | each old section key read through the namespace; a link and a token reference to the old topic; a `--dense` read; the topic list and a search for one section | A dropped, merged, or copied section; a changed title or `id`; a reference left on the old identity; a name listed twice; a section found twice |
+| FR14 | Docsite page-generation and route-resolution tests | a split namespace; a nested namespace; a package-page namespace; a namespace with a `category`, and one whose guides are all foundations docs; a generated topic level | An old address that stops resolving or lands in another sidebar group, a permanent guide redirect, a guide page on a non-package namespace, or a slug that is both a page and a redirect |
## Decision log
@@ -391,9 +407,24 @@ slug already belongs to the package.
Rejected: one docsite page per guide; it moves each split topic's address and
thins its page.
+### DEC-8 — Authoring owns integration authoring, and every doc has a named home
+
+**Reference:** `spec:AST-046/DEC-8`
+**Decider:** `josephfarina`, `2026-10-21`
+
+Maintainer decision: everything an integration author reads lives under one
+top-level home, `authoring`, which holds the integration guides and the field
+reference. No doc sits in a catch-all:
+a flat topic's home is named for what it is, Guides or Foundations, after the
+docsite's sidebar groups. Routes move with every reference, as DEC-3 allows,
+and topic names do not change.
+
+Rejected: keeping the integration guides under `cli` beside a separate
+reference, which gave authors two top-level homes; and a generated level a
+reader sees as "Unorganized".
+
## Open questions
-- **OQ1 — Where the `authoring` group's docs live in the tree.** (`human-api`)
- **OQ2 — What another provider's doc reads when it links to, extends, or
replaces a topic that becomes a namespace.** (`human-api`) FR13 moves every
reference inside the topic's own provider; a reference in another package
diff --git a/docs/specs/AST-047-navigable-output/spec.md b/docs/specs/AST-047-navigable-output/spec.md
index 040b79e5a4..b75e089ee7 100644
--- a/docs/specs/AST-047-navigable-output/spec.md
+++ b/docs/specs/AST-047-navigable-output/spec.md
@@ -45,8 +45,9 @@ This record owns the moves a read offers and how they appear in text and JSON.
the path of titles above it (`Astryx CLI › API › Functions › search()`).
- **FR2 — Up.** Every read except the top MUST offer the command that opens the
level it sits in: for a section, its topic's section list; for a node or a
- topic, the level it sits in (a guide's namespace, or the Unorganized level for
- a flat topic, `spec:AST-046` FR12); for a top-level namespace, the topic list.
+ topic, the level it sits in (a guide's namespace, or the Guides or Foundations
+ level for a flat topic, `spec:AST-046` FR12); for a top-level namespace, the
+ topic list.
- **FR3 — Down.** A read that has children MUST list them, each with its
summary, and give the command that opens one: a namespace its children, a
topic's index its sections, and the topic list its topics and namespaces. In text,
diff --git a/docs/specs/AST-050-app-themes/spec.md b/docs/specs/AST-050-app-themes/spec.md
index c21327f07e..f915545a7d 100644
--- a/docs/specs/AST-050-app-themes/spec.md
+++ b/docs/specs/AST-050-app-themes/spec.md
@@ -13,7 +13,7 @@ owners: [josephfarina]
affects_architecture: [architecture:cli-surface]
affects_families: []
affects_contributing: []
-affects_consumer_docs: [theme, cli/integrations, cli]
+affects_consumer_docs: [theme, authoring, cli]
---
# App themes system spec
diff --git a/docs/specs/AST-051-discover-integration-manager/spec.md b/docs/specs/AST-051-discover-integration-manager/spec.md
index 178ef757c1..c02e2a0e65 100644
--- a/docs/specs/AST-051-discover-integration-manager/spec.md
+++ b/docs/specs/AST-051-discover-integration-manager/spec.md
@@ -13,7 +13,7 @@ owners: [josephfarina]
affects_architecture: [architecture:cli-surface]
affects_families: []
affects_contributing: []
-affects_consumer_docs: [cli/integrations]
+affects_consumer_docs: [authoring]
---
# Discover integration manager system spec
@@ -186,7 +186,7 @@ source, packages}`. `source` has `name`, `generatedAt`, and `complete`. Each
cache directory (INV10).
- `spec:AST-031`: `discover` is a second named-export feature, without the
consent gate (FR6).
-- Consumer docs: `cli/integrations` gains the `discover` named export and config
+- Consumer docs: `authoring` gains the `discover` named export and config
field, and `astryx docs authoring` gains the `discover-source` section.
- `astryx discover` with no source configured listed only the project's
integrations. It also lists the official packages, first, each with the
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 8fbdc23823..e37f810678 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -37,12 +37,12 @@ The CLI documents itself, so these commands print what the installed version doe
`astryx docs cli/commands` lists every command, `astryx docs cli/api` lists
the API's functions, schemas, and enums, and a route such as
`astryx docs cli/api/functions/search` prints one.
-- `astryx docs authoring --index`: the authoring reference, with one section for
- each file an author writes: the `astryx.config.*` file, the
+- `astryx docs authoring/field-reference --index`: the field reference, with one
+ section for each file an author writes: the `astryx.config.*` file, the
`astryx.integration.*` manifest, codemods, and every doc type (`ComponentDoc`,
`TemplateDoc`, `ThemeDoc`, and the rest). Read one section with
`astryx docs authoring <section>`, for example `astryx docs authoring config`.
-- `astryx docs cli/integrations`: the guides to building an integration package,
+- `astryx docs authoring`: the guides to building an integration package,
from a quick start to publishing.
- `astryx docs`: every docs topic, including the design-system guides (for
example `tokens`, `theme`, and `layout`).
@@ -741,6 +741,6 @@ For the full walkthrough, from an empty folder to a published package, see the
guides:
```bash
-astryx docs cli/integrations
-astryx docs cli/integrations/quick-start
+astryx docs authoring
+astryx docs authoring/quick-start
```
diff --git a/packages/cli/api/component/doc-links.test.mjs b/packages/cli/api/component/doc-links.test.mjs
index 20947ac2fd..86a5b9a453 100644
--- a/packages/cli/api/component/doc-links.test.mjs
+++ b/packages/cli/api/component/doc-links.test.mjs
@@ -250,14 +250,14 @@ describe("a link in a guide's description, as the docs tree shows it", () => {
'Document a theme by extending the core theme topic, so an app reads it in `astryx docs theme`.';
const guide = /** @type {any} */ (
await docs(
- 'cli/integrations/building-blocks/themes/document-the-theme',
+ 'authoring/building-blocks/themes/document-the-theme',
undefined,
{cwd: tmpDir, full: true},
)
);
expect(guide.data.description).toBe(expected);
const namespace = /** @type {any} */ (
- await docs('cli/integrations/building-blocks/themes', undefined, {
+ await docs('authoring/building-blocks/themes', undefined, {
cwd: tmpDir,
})
);
diff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjs
index c695676595..1ff535cb7c 100644
--- a/packages/cli/api/docs/_adapter.mjs
+++ b/packages/cli/api/docs/_adapter.mjs
@@ -52,6 +52,7 @@ import {
cliDocSection,
} from '../../foundation/discovery/cli-self-docs.mjs';
import {
+ AUTHORING_REFERENCE_ROUTE,
loadAuthoringSelfDocs,
schemaFieldTable,
selfDocSection,
@@ -385,7 +386,7 @@ export function projectTree(catalog, {fresh = false} = {}) {
let cliTreeInputs;
/**
- * Every flat topic in the catalog, as the tree's Unorganized level reads it.
+ * Every flat topic in the catalog, as the tree's topic levels read it.
* @param {DocsCatalog} catalog
* @returns {Promise<import('../../foundation/doc-compiler/tree.mjs').TreeTopicInput[]>}
*/
@@ -394,12 +395,13 @@ async function flatTopicInputs(catalog) {
const topics = [];
for (const entry of catalog.entries()) {
const aliases = catalog.aliasesOf(entry);
- let {title, description} = entry;
- if (title == null || description == null) {
+ let {title, description, category} = entry;
+ if (title == null || description == null || category === undefined) {
try {
const file = await loadTopicFile(entry.path, null);
title ??= file.doc?.title;
description ??= file.doc?.description;
+ category ??= file.doc?.category;
} catch {
// A topic that does not load is reported where it is read.
}
@@ -410,6 +412,7 @@ async function flatTopicInputs(catalog) {
name: entry.name,
title: title ?? entry.name,
summary: description ?? '',
+ category: category ?? null,
source: `${entry.package}:${entry.name}`,
...(aliases.length > 0 ? {aliases} : {}),
});
@@ -419,7 +422,7 @@ async function flatTopicInputs(catalog) {
/**
* The CLI's tree, each configured integration's namespaces and guides, and
- * every flat topic in the generated Unorganized level.
+ * every flat topic in the generated level for its category.
* @param {DocsCatalog} catalog
* @param {boolean} fresh
* @returns {Promise<DocsTree>}
@@ -509,23 +512,22 @@ function identitiesOf(tree) {
}
/**
- * The CLI's authoring docs, by kind and name. `astryx docs authoring` reads
- * each as one section keyed by its name, so a link to one opens that section.
- * Loaded once per process, like the CLI's tree files.
+ * The CLI's authoring docs, by kind and name. The field reference under
+ * `astryx docs authoring` reads each as one section keyed by its name, so a
+ * link to one opens that section. Loaded once per process, like the CLI's
+ * tree files.
* @type {Promise<Map<string, any>> | undefined}
*/
let authoringDocs;
/**
- * The CLI authoring doc a link names, while `astryx docs authoring` is the
- * CLI's own topic.
- * @param {DocsCatalog} catalog
+ * The CLI authoring doc a link names. The `authoring` namespace is the CLI's
+ * own, so no integration can take its route.
* @param {string} kind
* @param {string} name
* @returns {Promise<any | null>}
*/
-async function authoringDoc(catalog, kind, name) {
- if (catalog.resolve('authoring')?.package !== CLI_PROVIDER_ID) return null;
+async function authoringDoc(kind, name) {
authoringDocs ??= loadAuthoringSelfDocs().then(
({loaded}) =>
new Map(loaded.map(({doc}) => [`${doc.type}\u0000${doc.name}`, doc])),
@@ -611,14 +613,14 @@ function docFinderOver(catalog, tree, fromProvider, summaries = true) {
}
const authored =
provider === CLI_PROVIDER_ID
- ? await authoringDoc(catalog, parsed.kind, parsed.name)
+ ? await authoringDoc(parsed.kind, parsed.name)
: null;
if (authored) {
return {
link: {
target,
id: createDocId(provider, authored.type, authored.name),
- route: 'authoring',
+ route: AUTHORING_REFERENCE_ROUTE,
title: authored.displayName ?? authored.name,
summary: authored.description ?? '',
command: `astryx docs authoring ${authored.name}`,
@@ -1428,7 +1430,7 @@ export function placeLinks(tree, node) {
/**
* The moves a topic read offers: from its place in the tree, where a guide
- * sits in its namespace and a flat topic in the Unorganized level.
+ * sits in its namespace and a flat topic in its topic level.
* @param {DocsCatalog} catalog
* @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
* @returns {Promise<import('./docs.type.mjs').DocsLinks>}
@@ -1526,7 +1528,7 @@ function treeArgument(catalog, tree, node) {
/**
* The doc that took a flat topic's route in the docs tree, when it is not
* that topic (spec:AST-046 FR11): the CLI keeps its routes, such as `cli`
- * and `unorganized`, and a namespace keeps its route over a topic of the same
+ * and `guides`, and a namespace keeps its route over a topic of the same
* name. Null when the topic owns its route, or the tree has no node there.
* @param {DocsTree} tree
* @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
@@ -1540,6 +1542,35 @@ export function routeOwner(tree, entry) {
: node;
}
+/**
+ * Routes that moved, old prefix first: the integration guides moved from
+ * `cli/integrations` (and, before that, the `cli-integrations` topic) into
+ * `authoring`, the one home for integration authors.
+ * Only the not-found error reads this, to name where a doc went; an old route
+ * opens nothing.
+ */
+const MOVED_ROUTES = [
+ ['cli/integrations', 'authoring'],
+ ['cli-integrations', 'authoring'],
+];
+
+/**
+ * The node an old route moved to, or null.
+ * @param {unknown} topic
+ * @param {DocsTree} tree
+ * @returns {TreeNode | null}
+ */
+function movedRoute(topic, tree) {
+ if (typeof topic !== 'string') return null;
+ const wanted = topic.toLowerCase();
+ for (const [from, to] of MOVED_ROUTES) {
+ if (wanted !== from && !wanted.startsWith(`${from}/`)) continue;
+ const node = tree.getFolded(`${to}${wanted.slice(from.length)}`);
+ if (node) return node;
+ }
+ return null;
+}
+
/**
* The error for a docs argument that names nothing. For a route, it suggests
* the children of the deepest namespace the route reaches; otherwise, every
@@ -1572,8 +1603,7 @@ export async function unknownTopicError(topic, catalog) {
}
if (suggestions.length === 0 && typeof topic === 'string') {
// The docs whose own name it is (`doctor` is cli/commands/doctor), or whose
- // route it spells with hyphens (`cli-integrations`, the guide's name before
- // it moved to cli/integrations).
+ // route it spells with hyphens (`cli-host-entry` is cli/host-entry).
const wanted = topic.toLowerCase();
suggestions = [...tree.nodes.values()]
.filter(
@@ -1592,6 +1622,19 @@ export async function unknownTopicError(topic, catalog) {
...catalog.names().map(name => ({name, reason: 'available topic'})),
];
}
+ // A route that moved names where it went, ahead of the usual suggestions
+ // (spec:AST-046 FR9, FR6).
+ const moved = movedRoute(topic, tree);
+ if (moved) {
+ return new AstryxError(
+ `Unknown topic "${String(topic)}". It moved to "${moved.route}"${notLoaded(catalog)}`,
+ [
+ {name: moved.route, reason: moved.summary},
+ ...suggestions.filter(entry => entry.name !== moved.route),
+ ],
+ ERROR_CODES.ERR_UNKNOWN_TOPIC,
+ );
+ }
return new AstryxError(
`Unknown topic "${String(topic)}"${notLoaded(catalog)}`,
suggestions,
diff --git a/packages/cli/api/docs/docs-homes.test.mjs b/packages/cli/api/docs/docs-homes.test.mjs
new file mode 100644
index 0000000000..8d2de3979b
--- /dev/null
+++ b/packages/cli/api/docs/docs-homes.test.mjs
@@ -0,0 +1,127 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Every Core doc has a named home in the docs tree (spec:AST-046 FR12).
+ *
+ * A reader sees a doc's home in its path (`Guides › Getting started`) and in
+ * its Up move. A flat Core topic sits in Guides or Foundations by the
+ * category it declares, so a new topic with no category, or one the levels
+ * do not know, fails here instead of landing in a catch-all. The integration
+ * guides and their field reference live under `authoring`, and the routes
+ * they left name where they went.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {docs} from './docs.mjs';
+import {TOPIC_LEVELS} from '../../foundation/doc-compiler/tree.mjs';
+
+const CLI = '@astryxdesign/cli';
+const SLOW = 60_000;
+
+describe('every Core doc has a named home', () => {
+ it(
+ 'puts each flat Core topic in Guides or Foundations by its category',
+ async () => {
+ const list = await docs();
+ const core = list.data.filter(topic => topic.package === CLI);
+ expect(core.length).toBeGreaterThan(10);
+ /** @type {string[]} */
+ const unfiled = [];
+ for (const topic of core) {
+ const read = await docs(topic.topic);
+ const {category} = read.data;
+ if (category !== 'guide' && category !== 'foundations') {
+ unfiled.push(`${topic.topic} (category ${String(category)})`);
+ continue;
+ }
+ const level =
+ category === 'foundations'
+ ? TOPIC_LEVELS.foundations
+ : TOPIC_LEVELS.guides;
+ expect(read.data.links.up, topic.topic).toBe(
+ `astryx docs ${level.route}`,
+ );
+ }
+ expect(unfiled, 'Core topics with no home: give each a category').toEqual(
+ [],
+ );
+ },
+ SLOW,
+ );
+
+ it(
+ 'lists each level under a plain name, and no catch-all',
+ async () => {
+ const list = await docs();
+ const roots = (list.meta.namespaces ?? []).map(entry => entry.topic);
+ expect(roots).toEqual(expect.arrayContaining(['guides', 'foundations']));
+ expect(roots).not.toContain('unorganized');
+ const guides = await docs('guides');
+ expect(guides.data).toMatchObject({route: 'guides', title: 'Guides'});
+ expect(guides.data.slots[0].children.map(child => child.route)).toEqual(
+ expect.arrayContaining(['getting-started', 'principles', 'theme']),
+ );
+ const foundations = await docs('foundations');
+ expect(foundations.data.title).toBe('Foundations');
+ expect(
+ foundations.data.slots[0].children.map(child => child.route),
+ ).toEqual(expect.arrayContaining(['color', 'icons', 'spacing']));
+ await expect(docs('unorganized')).rejects.toMatchObject({
+ code: 'ERR_UNKNOWN_TOPIC',
+ });
+ },
+ SLOW,
+ );
+
+ it(
+ 'keeps everything for integration authors under authoring, and names where an old route went',
+ async () => {
+ const authoring = await docs('authoring');
+ expect(authoring.data).toMatchObject({
+ route: 'authoring',
+ kind: 'namespace',
+ breadcrumb: [],
+ links: {up: 'astryx docs'},
+ });
+ const children = authoring.data.slots.flatMap(slot =>
+ slot.children.map(child => child.route),
+ );
+ expect(children).toEqual(
+ expect.arrayContaining([
+ 'authoring/quick-start',
+ 'authoring/building-blocks',
+ 'authoring/ship',
+ 'authoring/help',
+ 'authoring/field-reference',
+ ]),
+ );
+ // Every field reference section still opens from the namespace by its
+ // key, as `astryx docs authoring <name>` did on the topic (FR13).
+ const reference = await docs('authoring/field-reference', undefined, {
+ index: true,
+ });
+ const keys = reference.data.sections.map(section => section.id);
+ expect(keys.length).toBeGreaterThan(15);
+ for (const key of keys) {
+ const section = await docs('authoring', key);
+ expect(section.type, key).toBe('docs.detail.section');
+ expect(section.data.id, key).toBe(key);
+ }
+ for (const [old, now] of [
+ ['cli/integrations', 'authoring'],
+ ['cli/integrations/quick-start', 'authoring/quick-start'],
+ ['cli/integrations/ship/publishing', 'authoring/ship/publishing'],
+ ]) {
+ const error = await docs(old).catch(e => e);
+ expect(error).toMatchObject({
+ code: 'ERR_UNKNOWN_TOPIC',
+ message: expect.stringContaining(`It moved to "${now}"`),
+ });
+ // The new route comes first, ahead of the suggestions any unknown
+ // route gets (FR6).
+ expect(error.suggestions[0]).toMatchObject({name: now});
+ }
+ },
+ SLOW,
+ );
+});
diff --git a/packages/cli/api/docs/docs.doc.mjs b/packages/cli/api/docs/docs.doc.mjs
index e422c2a234..b53bed94bd 100644
--- a/packages/cli/api/docs/docs.doc.mjs
+++ b/packages/cli/api/docs/docs.doc.mjs
@@ -28,7 +28,7 @@ export const doc = {
'`cli/api` returns its children one level down (`depth` reads as many ' +
'levels as asked, and `detail` how much of each doc below), a typed doc such as ' +
"`cli/api/functions/search` returns its content, and a guide the tree " +
- 'places (`cli/integrations/quick-start`) reads like any topic. ' +
+ 'places (`authoring/quick-start`) reads like any topic. ' +
'Every read but the list carries `links`, the commands that move from it: ' +
'`up` to the level it sits in, `previous` and `next` to its neighbors, and, ' +
'for a typed doc, `related` to the docs it names (its command or function, ' +
@@ -162,12 +162,12 @@ export const doc = {
},
{
label: 'A namespace and everything below it, in full',
- code: "await docs('cli/integrations', undefined, {depth: 'all', detail: 'full'});",
+ code: "await docs('authoring', undefined, {depth: 'all', detail: 'full'});",
},
{label: 'One API function', code: "await docs('cli/api/functions/search');"},
{
label: 'A whole guide from the docs tree',
- code: "await docs('cli/integrations/quick-start');",
+ code: "await docs('authoring/quick-start');",
},
{label: 'One section by key', code: "await docs('spacing', 'scale');"},
],
diff --git a/packages/cli/api/docs/docs.test.mjs b/packages/cli/api/docs/docs.test.mjs
index a4bb180548..24d39266c4 100644
--- a/packages/cli/api/docs/docs.test.mjs
+++ b/packages/cli/api/docs/docs.test.mjs
@@ -93,7 +93,7 @@ describe('docs() dispatcher routing', () => {
it("lists the docs tree's namespaces in meta, so every data entry reads as a topic", async () => {
const res = await docs();
- expect(res.meta.namespaces.map(entry => entry.topic)).toEqual(['cli', 'global', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography', 'unorganized']);
+ expect(res.meta.namespaces.map(entry => entry.topic)).toEqual(['authoring', 'cli', 'foundations', 'global', 'guides', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography']);
for (const entry of res.data) {
expect((await docs(entry.topic)).type).toBe('docs.detail');
}
@@ -158,8 +158,8 @@ describe('docs() dispatcher routing', () => {
}, SLOW);
it('a guide the tree places reads like a topic: the whole doc, its index, a section', async () => {
- // cli/integrations is a namespace of short guides; each guide reads like a topic.
- const integrations = await docs('cli/integrations');
+ // authoring is a namespace of short guides; each guide reads like a topic.
+ const integrations = await docs('authoring');
expect(integrations.type).toBe('docs.node');
const guide = placedGuide(integrations.data);
expect((await docs(guide)).type).toBe('docs.detail');
@@ -178,7 +178,7 @@ describe('docs() dispatcher routing', () => {
expect(leaf.links.up).toBe('astryx docs cli/api/functions');
expect(leaf.links.previous).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);
expect(leaf.links.next).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);
- const integrations = (await docs('cli/integrations')).data;
+ const integrations = (await docs('authoring')).data;
const guide = placedGuide(integrations);
const siblings = integrations.slots
.find(slot => slot.children.some(child => child.route === guide))
@@ -187,7 +187,7 @@ describe('docs() dispatcher routing', () => {
const index = await docs(guide, undefined, {index: true});
// A guide moves across its namespace's slot, as any tree node does.
expect(index.data.links).toEqual({
- up: 'astryx docs cli/integrations',
+ up: 'astryx docs authoring',
...(at > 0 ? {previous: `astryx docs ${siblings[at - 1]}`} : {}),
...(at < siblings.length - 1
? {next: `astryx docs ${siblings[at + 1]}`}
@@ -204,16 +204,22 @@ describe('docs() dispatcher routing', () => {
expect(end.links.previous).toBe(
`astryx docs ${guide} ${index.data.sections.at(-2).id}`,
);
- // A flat topic's home is the Unorganized level, and it moves across it.
+ // A flat topic's home is the level for its category, and it moves across it.
const flat = (await docs('principles')).data.links;
- expect(flat.up).toBe('astryx docs unorganized');
+ expect(flat.up).toBe('astryx docs guides');
expect(flat.previous).toMatch(/^astryx docs [a-z-]+$/);
expect(flat.next).toMatch(/^astryx docs [a-z-]+$/);
- const home = (await docs('unorganized')).data;
- expect(home).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});
- expect(home.slots[0].children.map(child => child.route)).toEqual(
- (await docs()).data.map(entry => entry.topic),
- );
+ const guides = (await docs('guides')).data;
+ expect(guides).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});
+ const foundations = (await docs('foundations')).data;
+ expect(foundations).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});
+ // Between them the two levels hold every flat topic, each in list order.
+ const topics = (await docs()).data.map(entry => entry.topic);
+ const held = [guides, foundations].map(level => level.slots[0].children.map(child => child.route));
+ for (const routes of held) {
+ expect(routes).toEqual(topics.filter(topic => routes.includes(topic)));
+ }
+ expect(held.flat().sort()).toEqual([...topics].sort());
}, SLOW);
it('names a node by its doc identity; a generated level has id null', async () => {
@@ -240,10 +246,9 @@ describe('docs() dispatcher routing', () => {
}, SLOW);
it("the guide's old flat name is gone, and its error names the new route", async () => {
- await expect(docs('cli-integrations')).rejects.toMatchObject({
- code: 'ERR_UNKNOWN_TOPIC',
- suggestions: [expect.objectContaining({name: 'cli/integrations'})],
- });
+ const error = await docs('cli-integrations').catch(e => e);
+ expect(error.code).toBe('ERR_UNKNOWN_TOPIC');
+ expect(error.suggestions[0]).toMatchObject({name: 'authoring'});
expect((await docs()).data.map(entry => entry.topic)).not.toContain(
'cli-integrations',
);
@@ -253,11 +258,16 @@ describe('docs() dispatcher routing', () => {
const err = await docs('cli', 'zzzz-nope').catch(e => e);
expect(err).toBeInstanceOf(AstryxError);
expect(err.code).toBe('ERR_UNKNOWN_SECTION');
- // It names every guide below the namespace, at any depth.
const names = err.suggestions.map(s => s.name);
expect(names).toContain('cli/component-lookups');
- expect(names).toContain('cli/integrations/quick-start');
expect(names.every(name => name.startsWith('cli/'))).toBe(true);
+ // It names every guide below the namespace, at any depth.
+ const deep = await docs('authoring', 'zzzz-nope').catch(e => e);
+ expect(deep.code).toBe('ERR_UNKNOWN_SECTION');
+ const below = deep.suggestions.map(s => s.name);
+ expect(below).toContain('authoring/quick-start');
+ expect(below).toContain('authoring/building-blocks/components/add-a-component');
+ expect(below.every(name => name.startsWith('authoring/'))).toBe(true);
}, SLOW);
it('an unknown route suggests the children of the deepest namespace it reaches', async () => {
diff --git a/packages/cli/api/docs/integration-tree.test.mjs b/packages/cli/api/docs/integration-tree.test.mjs
index 6b7df74941..90e29a9fe6 100644
--- a/packages/cli/api/docs/integration-tree.test.mjs
+++ b/packages/cli/api/docs/integration-tree.test.mjs
@@ -246,7 +246,7 @@ describe('integration docs in the docs tree', () => {
});
scaffold({
...kit(),
- 'unorganized.doc.mjs': {...NAMESPACE, name: 'unorganized', title: 'Mine', summary: 'Mine.'},
+ 'guides.doc.mjs': {...NAMESPACE, name: 'guides', title: 'Mine', summary: 'Mine.'},
'use-a-theme.doc.mjs': {...NAMESPACE, name: 'use-a-theme', title: 'Acme use-a-theme', summary: 'Acme use-a-theme.'},
'cli.doc.mjs': flat('cli'),
});
@@ -254,26 +254,26 @@ describe('integration docs in the docs tree', () => {
expect(listed.meta.namespaces).toEqual(
expect.arrayContaining([
expect.objectContaining({topic: 'cli', package: '@astryxdesign/cli'}),
- expect.objectContaining({topic: 'unorganized', package: '@astryxdesign/cli'}),
+ expect.objectContaining({topic: 'guides', package: '@astryxdesign/cli'}),
]),
);
- expect(listed.meta.namespaces.filter(n => ['use-a-theme', 'unorganized'].includes(n.topic) && n.package === '@acme/kit')).toEqual([]);
+ expect(listed.meta.namespaces.filter(n => ['use-a-theme', 'guides'].includes(n.topic) && n.package === '@acme/kit')).toEqual([]);
expect(listed.data.map(entry => entry.topic)).not.toContain('cli');
// Each name opens the CLI's doc, and a CLI topic keeps its home.
expect((await docs('cli', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});
- expect((await docs('unorganized', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});
+ expect((await docs('guides', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'guides', package: '@astryxdesign/cli'});
const tokens = await docs('use-a-theme', undefined, {cwd: tmpDir});
expect(tokens.type).toBe('docs.detail');
- expect(tokens.data.links.up).toBe('astryx docs unorganized');
+ expect(tokens.data.links.up).toBe('astryx docs guides');
// The project doctor and the package doctor both name the claims.
const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});
expect(check.status).toBe('warn');
- expect(check.message).toContain('takes the route "unorganized", which the CLI\'s own docs keep');
+ expect(check.message).toContain('takes the route "guides", which the CLI\'s own docs keep');
expect(check.message).toContain('takes the route "use-a-theme"');
expect(check.message).toContain('both have the route "cli"');
const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
const graph = result.data.issues.filter(issue => issue.code === 'invalid_doc_graph').map(issue => issue.message).join('\n');
- expect(graph).toContain('takes the route "unorganized"');
+ expect(graph).toContain('takes the route "guides"');
expect(graph).toContain('takes the route "use-a-theme"');
expect(graph).toContain('route "cli"');
}, SLOW);
@@ -294,16 +294,16 @@ describe('integration docs in the docs tree', () => {
const nested = path.join(tmpDir, 'node_modules', '@acme', 'kit', 'docs', 'nested');
fs.mkdirSync(nested, {recursive: true});
fs.writeFileSync(
- path.join(nested, 'caps-unorganized.doc.mjs'),
- `export const docs = ${JSON.stringify(flat('Unorganized'), null, 2)};\n`,
+ path.join(nested, 'caps-guides.doc.mjs'),
+ `export const docs = ${JSON.stringify(flat('Guides'), null, 2)};\n`,
);
fs.writeFileSync(
path.join(nested, 'caps-use-a-theme.doc.mjs'),
`export const docs = ${JSON.stringify(flat('USE-A-THEME'), null, 2)};\n`,
);
expect((await docs('cli', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});
- expect((await docs('unorganized', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});
- expect((await docs('theme', undefined, {cwd: tmpDir, index: true})).data.links.up).toBe('astryx docs unorganized');
+ expect((await docs('guides', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'guides', package: '@astryxdesign/cli'});
+ expect((await docs('theme', undefined, {cwd: tmpDir, index: true})).data.links.up).toBe('astryx docs guides');
const listed = await docs(undefined, undefined, {cwd: tmpDir});
expect(listed.data.map(entry => entry.topic.toLowerCase())).not.toContain('cli');
// Search does not offer a topic whose route another doc owns.
@@ -314,10 +314,10 @@ describe('integration docs in the docs tree', () => {
const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});
expect(check.status).toBe('warn');
expect(check.message).toContain('route "CLI"');
- expect(check.message).toContain('takes the route "Unorganized"');
+ expect(check.message).toContain('takes the route "Guides"');
// `USE-A-THEME` is the CLI's topic `use-a-theme` in another spelling: the CLI's wins.
const tokens = await docs('USE-A-THEME', undefined, {cwd: tmpDir, index: true});
- expect(tokens.data).toMatchObject({name: 'use-a-theme', links: {up: 'astryx docs unorganized'}});
+ expect(tokens.data).toMatchObject({name: 'use-a-theme', links: {up: 'astryx docs guides'}});
expect(tokens.data.title).not.toBe('Acme USE-A-THEME');
const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
const graph = result.data.issues
@@ -325,7 +325,7 @@ describe('integration docs in the docs tree', () => {
.map(issue => issue.message)
.join('\n');
expect(graph).toContain('route "CLI"');
- expect(graph).toContain('takes the route "Unorganized"');
+ expect(graph).toContain('takes the route "Guides"');
}, SLOW);
it("keeps a replaced name for the topic that replaces it, over another integration's namespace", async () => {
@@ -420,9 +420,9 @@ describe('integration docs in the docs tree', () => {
scaffold({
...kit(),
'a-cli.doc.mjs': flat('cli'),
- 'a-unorganized.doc.mjs': flat('Unorganized'),
+ 'a-guides.doc.mjs': flat('Guides'),
'z-b2.doc.mjs': flat('b2', {replaces: 'cli'}),
- 'z-u2.doc.mjs': flat('u2', {replaces: 'Unorganized'}),
+ 'z-u2.doc.mjs': flat('u2', {replaces: 'Guides'}),
});
// Another package carries the chain on: c3 replaces b2, which replaced cli.
const three = path.join(tmpDir, 'node_modules', '@acme', 'three');
@@ -440,8 +440,8 @@ describe('integration docs in the docs tree', () => {
for (const name of ['cli', 'CLI']) {
expect((await docs(name, undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});
}
- for (const name of ['unorganized', 'UNORGANIZED']) {
- expect((await docs(name, undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});
+ for (const name of ['guides', 'GUIDES']) {
+ expect((await docs(name, undefined, {cwd: tmpDir})).data).toMatchObject({route: 'guides', package: '@astryxdesign/cli'});
}
// The replacement still answers to its own names.
for (const name of ['b2', 'c3']) {
@@ -456,7 +456,7 @@ describe('integration docs in the docs tree', () => {
const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});
expect(check.status).toBe('warn');
expect(check.message).toContain('The topic "c3" answers to "cli" through replaces');
- expect(check.message).toContain('The topic "u2" answers to "unorganized" through replaces');
+ expect(check.message).toContain('The topic "u2" answers to "guides" through replaces');
const inPackage = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
const graph = inPackage.data.issues
.filter(issue => issue.code === 'invalid_doc_graph')
@@ -519,7 +519,7 @@ describe('integration docs in the docs tree', () => {
});
const {data} = await docs('theme', 'acme-theming-notes', {cwd: tmpDir});
// `generic:integrations` is the extension's own guide, never the CLI's
- // `cli/integrations`; a provider-qualified link reaches the CLI's topic.
+ // `authoring`; a provider-qualified link reaches the CLI's topic.
expect(data.content[0].text).toBe(
'See `astryx docs acme/integrations`, and `astryx docs tokens` for the tokens.',
);
diff --git a/packages/cli/api/docs/integrationDocs.test.mjs b/packages/cli/api/docs/integrationDocs.test.mjs
index cd44377a1d..53789626b2 100644
--- a/packages/cli/api/docs/integrationDocs.test.mjs
+++ b/packages/cli/api/docs/integrationDocs.test.mjs
@@ -447,7 +447,7 @@ describe('integration-contributed topics', () => {
// places it.
expect(top).toContain('troubleshooting');
expect(
- top.some(name => /^cli\/integrations\/(?:.+\/)?troubleshooting$/.test(name)),
+ top.some(name => /^authoring\/(?:.+\/)?troubleshooting$/.test(name)),
top.join(', '),
).toBe(true);
}, SLOW);
diff --git a/packages/cli/api/docs/namespace-section.test.mjs b/packages/cli/api/docs/namespace-section.test.mjs
index 3826e95292..d5be93a0c3 100644
--- a/packages/cli/api/docs/namespace-section.test.mjs
+++ b/packages/cli/api/docs/namespace-section.test.mjs
@@ -157,13 +157,13 @@ describe('a section read on a namespace', () => {
expect(names).toContain('layout/side-panels');
expect(names.every(name => name.startsWith('layout/'))).toBe(true);
// At any depth: guides under nested namespaces are named, namespaces are not.
- const cli = await docs('cli', 'zzzz-nope').catch(e => e);
- expect(cli.code).toBe('ERR_UNKNOWN_SECTION');
- expect(cli.suggestions.map(s => s.name)).toContain(
- 'cli/integrations/quick-start',
+ const authoring = await docs('authoring', 'zzzz-nope').catch(e => e);
+ expect(authoring.code).toBe('ERR_UNKNOWN_SECTION');
+ expect(authoring.suggestions.map(s => s.name)).toContain(
+ 'authoring/building-blocks/components/add-a-component',
);
- expect(cli.suggestions.map(s => s.name)).not.toContain(
- 'cli/integrations',
+ expect(authoring.suggestions.map(s => s.name)).not.toContain(
+ 'authoring/building-blocks',
);
},
SLOW,
diff --git a/packages/cli/api/docs/reference-blocks.test.mjs b/packages/cli/api/docs/reference-blocks.test.mjs
index 9861bceb8d..05765669c8 100644
--- a/packages/cli/api/docs/reference-blocks.test.mjs
+++ b/packages/cli/api/docs/reference-blocks.test.mjs
@@ -300,11 +300,11 @@ describe('a reference block that includes what it names', () => {
});
describe('what a reference block names', () => {
- it('resolves a CLI authoring schema by identity, to its section of `astryx docs authoring`', async () => {
+ it('resolves a CLI authoring schema by identity, to its section of the field reference', async () => {
const resolve = await linkResolver(builtinCatalog(), CLI_PROVIDER_ID);
expect(await resolve('schema:integration')).toMatchObject({
id: createDocId(CLI_PROVIDER_ID, 'schema', 'integration'),
- route: 'authoring',
+ route: 'authoring/field-reference',
title: 'Astryx Integration',
command: 'astryx docs authoring integration',
});
diff --git a/packages/cli/api/doctor/doctor.mjs b/packages/cli/api/doctor/doctor.mjs
index b3e56cc657..79d1167c5b 100644
--- a/packages/cli/api/doctor/doctor.mjs
+++ b/packages/cli/api/doctor/doctor.mjs
@@ -1048,16 +1048,20 @@ function nameTypes(names) {
}
/**
- * The section keys `astryx docs authoring --index` lists, read the way that
- * command reads them.
+ * The section keys the field reference lists (`astryx docs
+ * authoring/field-reference --index`), read the way that command reads them.
* @returns {Promise<{keys: Set<string>} | {keys: null, error: string}>}
*/
async function authoringTopicKeys() {
try {
+ const {AUTHORING_REFERENCE_ROUTE} =
+ await import('../../foundation/discovery/authoring-self-docs.mjs');
const catalog = DocsCatalog.fromBuiltins();
- const entry = catalog.resolve('authoring');
- if (!entry) return {keys: null, error: 'it is not a built-in topic'};
- const index = indexView(await lowerTopic(catalog, entry));
+ const node = (await projectTree(catalog)).get(AUTHORING_REFERENCE_ROUTE);
+ if (!node?.ref?.topicFile) {
+ return {keys: null, error: 'the docs tree has no field reference'};
+ }
+ const index = indexView(await lowerTopic(catalog, guideEntry(node)));
return {keys: new Set(index.sections.map(section => section.id))};
} catch (err) {
return {
@@ -1076,7 +1080,7 @@ function surfaceProblems(surface) {
const problems = [];
if (surface.types === 0 && surface.untraced.length === 0) {
problems.push(
- `@astryxdesign/cli/authoring exports no types, so nothing was compared with \`${formatCliCommand('docs authoring')}\``,
+ `@astryxdesign/cli/authoring exports no types, so nothing was compared with \`${formatCliCommand('docs authoring/field-reference')}\``,
);
}
for (const {module, names, reason, source, key} of surface.unreadable) {
@@ -1089,7 +1093,7 @@ function surfaceProblems(surface) {
? `${source} does not load`
: `${source} renders section "${key}", which the topic's index does not list`;
problems.push(
- `${nameTypes(names)} from ${module} ${names.length === 1 ? 'has' : 'have'} no doc in \`${formatCliCommand('docs authoring')}\`: ${why}`,
+ `${nameTypes(names)} from ${module} ${names.length === 1 ? 'has' : 'have'} no doc in \`${formatCliCommand('docs authoring/field-reference')}\`: ${why}`,
);
}
for (const {name, reason} of surface.untraced) {
@@ -1130,7 +1134,7 @@ export async function checkAuthoringDocs(_ctx, options = {}) {
const audit = await auditAuthoringSelfDocs({root, sources});
const problems = [
...audit.unreachable.map(
- source => `${source} is not in \`${formatCliCommand('docs authoring')}\``,
+ source => `${source} is not in \`${formatCliCommand('docs authoring/field-reference')}\``,
),
...audit.failed.map(
({source, error}) => `${source} failed to load: ${error}`,
@@ -1146,7 +1150,7 @@ export async function checkAuthoringDocs(_ctx, options = {}) {
: {keys: options.topicKeys};
const surface = [
...('error' in topic
- ? [`\`${formatCliCommand('docs authoring')}\` could not be read: ${topic.error}`]
+ ? [`\`${formatCliCommand('docs authoring/field-reference')}\` could not be read: ${topic.error}`]
: []),
...surfaceProblems(
await auditAuthoringSurface({root, sources, topicKeys: topic.keys}),
@@ -1170,7 +1174,7 @@ export async function checkAuthoringDocs(_ctx, options = {}) {
id,
label,
status: 'pass',
- message: `All ${audit.sections} authoring schemas are readable in \`${formatCliCommand('docs authoring')}\`.`,
+ message: `All ${audit.sections} authoring schemas are readable in \`${formatCliCommand('docs authoring/field-reference')}\`.`,
};
} catch (err) {
return {
@@ -1238,7 +1242,7 @@ export async function checkCliDocs(_ctx, options = {}) {
id,
label,
status: 'pass',
- message: `All ${audit.docs} CLI docs are readable: ${audit.tree} in the \`${formatCliCommand('docs cli')}\` tree and ${audit.authoring} in \`${formatCliCommand('docs authoring')}\`.`,
+ message: `All ${audit.docs} CLI docs are readable: ${audit.tree} in the \`${formatCliCommand('docs cli')}\` tree and ${audit.authoring} in \`${formatCliCommand('docs authoring/field-reference')}\`.`,
};
} catch (err) {
return {
@@ -1355,7 +1359,7 @@ export async function checkDocsProgressiveDisclosure(ctx) {
// A guide the docs tree places is a topic read by its route; it is held
// to the same budget as every flat topic.
const guides = [...(await projectTree(catalog)).nodes.values()]
- // A flat topic in the Unorganized level is checked above, as a topic.
+ // A flat topic in a topic level is checked above, as a topic.
.filter(node => node.kind === 'generic' && !node.ref?.flatTopic)
.map(guideEntry);
for (const entry of [...catalog.entries(), ...guides]) {
diff --git a/packages/cli/api/doctor/doctor.test.mjs b/packages/cli/api/doctor/doctor.test.mjs
index 3593b0f325..1d871051ab 100644
--- a/packages/cli/api/doctor/doctor.test.mjs
+++ b/packages/cli/api/doctor/doctor.test.mjs
@@ -652,7 +652,7 @@ describe('checkAuthoringDocs', () => {
it('passes when every authoring self-doc is reachable and fits one read', async () => {
const c = await checkAuthoringDocs();
expect(c).toMatchObject({id: 'authoring-docs', status: 'pass'});
- expect(c.message).toContain(formatCliCommand('docs authoring'));
+ expect(c.message).toContain(formatCliCommand('docs authoring/field-reference'));
}, SLOW);
});
@@ -680,7 +680,7 @@ describe('checkCliDocs', () => {
id: 'cli-docs',
label: 'CLI docs',
status: 'pass',
- message: `All ${audit.docs} CLI docs are readable: ${audit.tree} in the \`${formatCliCommand('docs cli')}\` tree and ${audit.authoring} in \`${formatCliCommand('docs authoring')}\`.`,
+ message: `All ${audit.docs} CLI docs are readable: ${audit.tree} in the \`${formatCliCommand('docs cli')}\` tree and ${audit.authoring} in \`${formatCliCommand('docs authoring/field-reference')}\`.`,
});
},
SLOW,
@@ -790,7 +790,7 @@ describe('checkDocsTree', () => {
describe('checkAuthoringDocs against the public authoring surface', () => {
const NAMESPACE = 'doctypes/namespace/namespace.doc.mjs';
const NAMESPACE_TYPES =
- `NamespaceDoc, NamespaceProviderScope, NamespaceSlotAcceptance, NamespaceSlot, NamespaceAdoptionSource, NamespaceAdoptionRule from doctypes/namespace/type.ts have no doc in \`${formatCliCommand('docs authoring')}\``;
+ `NamespaceDoc, NamespaceProviderScope, NamespaceSlotAcceptance, NamespaceSlot, NamespaceAdoptionSource, NamespaceAdoptionRule from doctypes/namespace/type.ts have no doc in \`${formatCliCommand('docs authoring/field-reference')}\``;
const SURFACE_FIX =
'Put a self-doc beside each module whose types @astryxdesign/cli/authoring exports and list it in AUTHORING_SELF_DOCS; export what each listed self-doc documents, or remove that self-doc.';
@@ -820,7 +820,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
id: 'authoring-docs',
label: 'Authoring docs',
status: 'pass',
- message: `All ${AUTHORING_SELF_DOCS.length} authoring schemas are readable in \`${formatCliCommand('docs authoring')}\`.`,
+ message: `All ${AUTHORING_SELF_DOCS.length} authoring schemas are readable in \`${formatCliCommand('docs authoring/field-reference')}\`.`,
});
},
SLOW,
@@ -849,7 +849,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
});
expect(c.status).toBe('fail');
expect(c.message).toBe(
- `2 problems: ${NAMESPACE} is not in \`${formatCliCommand('docs authoring')}\`; ${NAMESPACE_TYPES}: ${NAMESPACE} is not listed in AUTHORING_SELF_DOCS`,
+ `2 problems: ${NAMESPACE} is not in \`${formatCliCommand('docs authoring/field-reference')}\`; ${NAMESPACE_TYPES}: ${NAMESPACE} is not listed in AUTHORING_SELF_DOCS`,
);
},
SLOW,
@@ -858,7 +858,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
it(
"fails when the topic's index no longer exposes the NamespaceDoc section",
async () => {
- const index = await docs('authoring', undefined, {index: true});
+ const index = await docs('authoring/field-reference', undefined, {index: true});
const topicKeys = new Set(
index.data.sections
.map((/** @type {any} */ s) => s.id)
@@ -947,7 +947,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
expect(c.fix).toBe(SURFACE_FIX);
expect(c.message).toMatch(
new RegExp(
- `^[A-Za-z, ]+ from ${escape(module)} have no doc in \`${escape(formatCliCommand('docs authoring'))}\`: no self-doc sits beside ${escape(module)}$`,
+ `^[A-Za-z, ]+ from ${escape(module)} have no doc in \`${escape(formatCliCommand('docs authoring/field-reference'))}\`: no self-doc sits beside ${escape(module)}$`,
),
);
for (const name of names) {
@@ -990,7 +990,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
expect(await checkAuthoringDocs()).toMatchObject({
status: 'fail',
message:
- `\`${formatCliCommand('docs authoring')}\` could not be read: no built-in docs`,
+ `\`${formatCliCommand('docs authoring/field-reference')}\` could not be read: no built-in docs`,
fix: SURFACE_FIX,
});
} finally {
@@ -1011,7 +1011,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
const c = await checkAuthoringDocs(undefined, {root});
expect(c.status).toBe('fail');
expect(c.message).toContain(
- `@astryxdesign/cli/authoring exports no types, so nothing was compared with \`${formatCliCommand('docs authoring')}\``,
+ `@astryxdesign/cli/authoring exports no types, so nothing was compared with \`${formatCliCommand('docs authoring/field-reference')}\``,
);
},
SLOW,
diff --git a/packages/cli/api/search/_candidate-score.mjs b/packages/cli/api/search/_candidate-score.mjs
index 2513379508..87a66d8ad8 100644
--- a/packages/cli/api/search/_candidate-score.mjs
+++ b/packages/cli/api/search/_candidate-score.mjs
@@ -104,7 +104,7 @@ export function scoreCandidate(
for (const candidateName of [name, ...aliases.filter(Boolean)]) {
const nameLower = candidateName.toLowerCase();
// A placed guide's name is its route, and the route's last segment is its
- // name too, as a flat topic's is: `codemods` is cli/integrations/codemods.
+ // name too, as a flat topic's is: `codemods` is authoring/building-blocks/codemods.
const leafLower = nameLower.slice(nameLower.lastIndexOf('/') + 1);
// A plural of the name is the name: `integration` is the `integrations`
diff --git a/packages/cli/api/search/_gather-docs.mjs b/packages/cli/api/search/_gather-docs.mjs
index 463aa20542..07d150bf43 100644
--- a/packages/cli/api/search/_gather-docs.mjs
+++ b/packages/cli/api/search/_gather-docs.mjs
@@ -63,7 +63,7 @@ export async function gatherDocs(cwd) {
// integration issues; search just cannot index it.
}
const doc = lowered?.doc ?? null;
- // A flat topic lives in the Unorganized level; its hits say so, and name
+ // A flat topic lives in its topic level; its hits say so, and name
// the package each section came from.
const home = tree?.get(entry.name);
const placed = home?.ref?.flatTopic === entry.name ? home : null;
@@ -176,7 +176,7 @@ export async function gatherDocs(cwd) {
* @param {string} [path] - where the topic lives in the docs tree, as titles
* joined by ` › `; a flat topic is its own title
* @param {string} [parent] - the command that opens the level above the
- * topic: its namespace, or the Unorganized level for a flat topic
+ * topic: its namespace, or the topic level for a flat topic
* @param {string} [pkg] - the npm package that authored the topic
* @param {(key: string) => string} [sectionPackage] - the npm package a
* section came from: an extension's section names the extension's package
@@ -197,7 +197,7 @@ function topicCandidates(
const docTitle = path || doc?.title || title || name;
const split = sections.length > 1;
// A placed guide also answers to its last route segment's words:
- // `quick start` is cli/integrations/quick-start.
+ // `quick start` is authoring/quick-start.
const leaf = name.slice(name.lastIndexOf('/') + 1);
/** @type {Candidate[]} */
const out = [
diff --git a/packages/cli/api/search/search.doc.mjs b/packages/cli/api/search/search.doc.mjs
index 805d5e9b38..eae78ae1c5 100644
--- a/packages/cli/api/search/search.doc.mjs
+++ b/packages/cli/api/search/search.doc.mjs
@@ -58,7 +58,7 @@ export const doc = {
{
type: 'search',
description:
- 'The query echoed back, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit`: each has domain, name, score, reason, description, and follow-up command, plus `import` for components and hooks, `title` for docs, `displayName` and `kind` for templates, and `displayName` for themes. A doc result is the smallest part that answers: one section (with `section`, and a command that reads only it), one docs-tree route, or a topic, whose command lists its sections. `parent` is the command that opens the level above it: the section list of its topic, the namespace a tree node sits in, the Unorganized level for a flat topic, or the topic list for a top-level namespace. Every doc result also carries `package`, the npm package that authored it (for a section, the package its file came from). A theme result is one theme you can import: `name` is its slug, its command is `astryx theme add <slug>` (outside a project, where there is no app to add it to, `astryx theme eject <slug>`), and `package` is the npm package that ships it (`@astryxdesign/cli` for the CLI\'s own themes). When a search with no `type` could not obtain @astryxdesign/core, `meta.partial` is `{skipped, reason}`: the domains it skipped (`component`, `hook`, `template`) and why; the results are the docs and themes, and text mode prints one line on standard error.',
+ 'The query echoed back, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit`: each has domain, name, score, reason, description, and follow-up command, plus `import` for components and hooks, `title` for docs, `displayName` and `kind` for templates, and `displayName` for themes. A doc result is the smallest part that answers: one section (with `section`, and a command that reads only it), one docs-tree route, or a topic, whose command lists its sections. `parent` is the command that opens the level above it: the section list of its topic, the namespace a tree node sits in, the topic level (Guides or Foundations) for a flat topic, or the topic list for a top-level namespace. Every doc result also carries `package`, the npm package that authored it (for a section, the package its file came from). A theme result is one theme you can import: `name` is its slug, its command is `astryx theme add <slug>` (outside a project, where there is no app to add it to, `astryx theme eject <slug>`), and `package` is the npm package that ships it (`@astryxdesign/cli` for the CLI\'s own themes). When a search with no `type` could not obtain @astryxdesign/core, `meta.partial` is `{skipped, reason}`: the domains it skipped (`component`, `hook`, `template`) and why; the results are the docs and themes, and text mode prints one line on standard error.',
},
],
throws: [
diff --git a/packages/cli/api/search/search.test.mjs b/packages/cli/api/search/search.test.mjs
index fe63cbc0b1..affae4dba5 100644
--- a/packages/cli/api/search/search.test.mjs
+++ b/packages/cli/api/search/search.test.mjs
@@ -117,16 +117,16 @@ describe('search leaf — docs at the grain a reader reads them', () => {
.find(result => result.section === 'which-codemods-run');
expect(hit).toMatchObject({
domain: 'doc',
- name: expect.stringMatching(/^cli\/integrations\/(?:.+\/)?codemods$/),
+ name: expect.stringMatching(/^authoring\/(?:.+\/)?codemods$/),
title: expect.stringMatching(/ › Codemods › Choose when a codemod runs$/),
});
expect(hit.parent).toBe(`astryx docs ${hit.name} --index`);
expect(hit.command).toBe(`astryx docs ${hit.name} which-codemods-run`);
const block = await search('token-ref', {cwd});
expect(block.data.results[0]).toMatchObject({
- name: 'authoring',
+ name: 'authoring/field-reference',
section: 'reference-doc',
- command: 'astryx docs authoring reference-doc',
+ command: 'astryx docs authoring/field-reference reference-doc',
});
const fn = await search('assertResponse', {cwd, type: 'doc'});
expect(fn.data.results[0]).toMatchObject({
@@ -148,13 +148,13 @@ describe('search leaf — docs at the grain a reader reads them', () => {
// keywords and the title the guides declare. A namespace's own
// keywords count, and a plural name is the name.
for (const [query, route] of [
- ['make an integration', /^cli\/integrations$/],
- ['build an integration', /^cli\/integrations$/],
- ['create an integration', /^cli\/integrations$/],
- ['integration', /^cli\/integrations$/],
- ['publish an integration', /^cli\/integrations$/],
+ ['make an integration', /^authoring$/],
+ ['build an integration', /^authoring$/],
+ ['create an integration', /^authoring$/],
+ ['integration', /^authoring$/],
+ ['publish an integration', /^authoring$/],
// The troubleshooting guide, wherever the tree places it.
- ['troubleshoot integration', /^cli\/integrations\/(?:.+\/)?troubleshooting$/],
+ ['troubleshoot integration', /^authoring\/(?:.+\/)?troubleshooting$/],
]) {
const r = await search(query, {cwd, type: 'doc'});
const names = r.data.results.slice(0, 3).map(result => result.name);
@@ -167,7 +167,7 @@ describe('search leaf — docs at the grain a reader reads them', () => {
it(
'gives a top-level namespace hit the topic list as its parent',
async () => {
- for (const [query, route] of [['unorganized', 'unorganized'], ['Astryx CLI', 'cli']]) {
+ for (const [query, route] of [['foundations', 'foundations'], ['Astryx CLI', 'cli']]) {
const r = await search(query, {cwd, type: 'doc'});
expect(r.data.results).toContainEqual(
expect.objectContaining({
@@ -185,7 +185,7 @@ describe('search leaf — docs at the grain a reader reads them', () => {
'points a topic hit at its index, never a whole-topic read',
async () => {
// A guide the tree places, read from the tree rather than named.
- const {data: integrations} = await docs('cli/integrations');
+ const {data: integrations} = await docs('authoring');
const guide = integrations.slots
.flatMap(slot => slot.children)
.find(child => child.kind === 'generic').route;
@@ -440,9 +440,9 @@ describe('search leaf — a candidate that matches every word outranks a partial
const tokens = await search('tokens', {cwd});
expect(tokens.data.results[0]).toMatchObject({domain: 'doc', name: 'tokens'});
for (const [query, route] of [
- ['codemods', /^cli\/integrations\/(?:.+\/)?codemods$/],
- ['quick start', /^cli\/integrations\/(?:.+\/)?quick-start$/],
- ['test in an app', /^cli\/integrations\/(?:.+\/)?test-in-an-app$/],
+ ['codemods', /^authoring\/(?:.+\/)?codemods$/],
+ ['quick start', /^authoring\/(?:.+\/)?quick-start$/],
+ ['test in an app', /^authoring\/(?:.+\/)?test-in-an-app$/],
]) {
const r = await search(query, {cwd, type: 'doc'});
// The guide is among the hits that share the top score: two guides
diff --git a/packages/cli/assets/docs/author-a-theme.doc.mjs b/packages/cli/assets/docs/author-a-theme.doc.mjs
index e57908c3ee..2d06eef329 100644
--- a/packages/cli/assets/docs/author-a-theme.doc.mjs
+++ b/packages/cli/assets/docs/author-a-theme.doc.mjs
@@ -28,7 +28,7 @@ export const docs = {
{type: 'code', lang: 'json', label: 'Minimal palette config (palette.config.json)', code: '{"families": [{"id": "ocean", "seed": "#0074e2"}]}'},
{type: 'code', lang: 'bash', label: 'Generate and preview', code: '# Print the palette without writing files\nastryx theme palette generate palette.config.json\n\n# Write palette + receipt, and open a visual preview\nastryx theme palette generate palette.config.json \\\n --out src/themes/ocean/tokens/ocean.palette.ts \\\n --preview preview.html'},
{type: 'prose', text: "The command writes a `.ts` file exporting 21 shades (stops 0–100) for both light and dark, plus a `.receipt.json` to regenerate later. Point your theme's tokens at the palette, then run defineTheme (see below)."},
- {type: 'prose', text: 'For the full palette config fields and CLI flags, run `astryx docs cli/commands/theme-palette-generate`. For the integration-authoring walkthrough of connecting a palette to theme tokens, run `astryx docs cli/integrations/building-blocks/themes/generate-a-palette`.'},
+ {type: 'prose', text: 'For the full palette config fields and CLI flags, run `astryx docs cli/commands/theme-palette-generate`. For the integration-authoring walkthrough of connecting a palette to theme tokens, run `astryx docs authoring/building-blocks/themes/generate-a-palette`.'},
],
},
{
@@ -61,7 +61,7 @@ export const docs = {
['adaptations', 'Width-breakpoint overrides merge by fixed name. Inherited ordered rules keep their relative order; child rules append and re-resolve against the child root axes.'],
]},
{type: 'prose', text: "Inheritance is resolved when the theme is defined, so an extended theme is flat: `astryx theme build` emits one self-contained stylesheet holding everything the child inherited, and the base theme's CSS does not need to be loaded next to it. A base that is not a theme (most often an import that missed) throws when `defineTheme` runs, rather than producing a theme that silently inherits nothing."},
- {type: 'prose', text: 'For the integration-specific guidance on mapping a palette to tokens when extending, see `astryx docs cli/integrations/building-blocks/themes/define-the-theme`.'},
+ {type: 'prose', text: 'For the integration-specific guidance on mapping a palette to tokens when extending, see `astryx docs authoring/building-blocks/themes/define-the-theme`.'},
],
},
{
diff --git a/packages/cli/assets/docs/tree/add-a-component.doc.mjs b/packages/cli/assets/docs/tree/add-a-component.doc.mjs
index ecd95e73aa..49795799c4 100644
--- a/packages/cli/assets/docs/tree/add-a-component.doc.mjs
+++ b/packages/cli/assets/docs/tree/add-a-component.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/components/add-a-component`: choose a
+ * @file `astryx docs authoring/building-blocks/components/add-a-component`: choose a
* component name and generate its first source and doc files.
*/
diff --git a/packages/cli/assets/docs/tree/add-a-theme.doc.mjs b/packages/cli/assets/docs/tree/add-a-theme.doc.mjs
index 2a363824df..844f53338d 100644
--- a/packages/cli/assets/docs/tree/add-a-theme.doc.mjs
+++ b/packages/cli/assets/docs/tree/add-a-theme.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/themes/add-a-theme`:
+ * @file `astryx docs authoring/building-blocks/themes/add-a-theme`:
* scaffold a theme in a package — blank, or forked from an existing theme.
*/
diff --git a/packages/cli/assets/docs/tree/add-a-topic.doc.mjs b/packages/cli/assets/docs/tree/add-a-topic.doc.mjs
index cbb77e8a29..036a01b3ab 100644
--- a/packages/cli/assets/docs/tree/add-a-topic.doc.mjs
+++ b/packages/cli/assets/docs/tree/add-a-topic.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/docs/add-a-topic`: add a
+ * @file `astryx docs authoring/building-blocks/docs/add-a-topic`: add a
* doc topic to an integration package, write its sections, and pick the doc
* kind for each thing the package ships.
*/
diff --git a/packages/cli/assets/docs/tree/agent-guidance.doc.mjs b/packages/cli/assets/docs/tree/agent-guidance.doc.mjs
index fdf4b25331..a3d6b44497 100644
--- a/packages/cli/assets/docs/tree/agent-guidance.doc.mjs
+++ b/packages/cli/assets/docs/tree/agent-guidance.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/configuration/agent-guidance`: add short lines of
+ * @file `astryx docs authoring/building-blocks/configuration/agent-guidance`: add short lines of
* guidance that apps put in front of their AI agents, within the limits.
*/
diff --git a/packages/cli/assets/docs/tree/integrations.doc.mjs b/packages/cli/assets/docs/tree/authoring.doc.mjs
similarity index 79%
rename from packages/cli/assets/docs/tree/integrations.doc.mjs
rename to packages/cli/assets/docs/tree/authoring.doc.mjs
index 05283d6eed..f2120fc731 100644
--- a/packages/cli/assets/docs/tree/integrations.doc.mjs
+++ b/packages/cli/assets/docs/tree/authoring.doc.mjs
@@ -1,27 +1,36 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-/** @file astryx docs cli/integrations — build an integration package. */
+/**
+ * @file `astryx docs authoring`: everything for integration authors. The
+ * guides build, ship, and fix an integration package; the field reference
+ * covers every file it holds.
+ */
/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
export const docs = {
type: 'namespace',
- name: 'integrations',
- placement: {parent: 'namespace:cli', slot: 'guides', order: 10},
- title: 'Build an integration',
+ name: 'authoring',
+ title: 'Authoring',
summary:
- 'Build an npm package that adds components, templates, themes, docs, and codemods to Astryx apps.',
+ 'Build an npm package that adds components, templates, themes, docs, and codemods to Astryx apps, and look up every field of every file it holds.',
keywords: [
+ 'authoring',
'integration',
'integration package',
'make an integration',
'publish an integration',
'integration authoring',
+ 'authoring reference',
],
slots: {
guides: {
title: 'Build an integration',
accepts: {kinds: ['generic', 'namespace']},
},
+ reference: {
+ title: 'Reference',
+ accepts: {kinds: ['generic']},
+ },
},
blocks: [
{
@@ -42,7 +51,7 @@ export const docs = {
},
{
type: 'prose',
- text: 'Every field of every file you write for an integration is in {@link generic:authoring}.',
+ text: 'Every field of every file you write for an integration is in {@link generic:field-reference}.',
},
{
type: 'prose',
diff --git a/packages/cli/assets/docs/tree/block-template.doc.mjs b/packages/cli/assets/docs/tree/block-template.doc.mjs
index 33940eb0eb..571d72b2df 100644
--- a/packages/cli/assets/docs/tree/block-template.doc.mjs
+++ b/packages/cli/assets/docs/tree/block-template.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template/block-template`:
+ * @file `astryx docs authoring/building-blocks/templates/document-the-template/block-template`:
* the block-only fields: component relationships and the preview shape.
*/
diff --git a/packages/cli/assets/docs/tree/build-the-template.doc.mjs b/packages/cli/assets/docs/tree/build-the-template.doc.mjs
index 9adc96e4b0..14ec102244 100644
--- a/packages/cli/assets/docs/tree/build-the-template.doc.mjs
+++ b/packages/cli/assets/docs/tree/build-the-template.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template`:
+ * @file `astryx docs authoring/building-blocks/templates/build-the-template`:
* author portable template source and every asset that source needs.
*/
diff --git a/packages/cli/assets/docs/tree/building-blocks.doc.mjs b/packages/cli/assets/docs/tree/building-blocks.doc.mjs
index 1d6b6cd452..a9070a55cd 100644
--- a/packages/cli/assets/docs/tree/building-blocks.doc.mjs
+++ b/packages/cli/assets/docs/tree/building-blocks.doc.mjs
@@ -1,12 +1,12 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-/** @file astryx docs cli/integrations/building-blocks — the kinds you can add. */
+/** @file astryx docs authoring/building-blocks — the kinds you can add. */
/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
export const docs = {
type: 'namespace',
name: 'building-blocks',
- placement: {parent: 'namespace:integrations', slot: 'guides', order: 20},
+ placement: {parent: 'namespace:authoring', slot: 'guides', order: 20},
title: 'Building Blocks',
summary:
'Add components, templates, themes, docs, and codemods, and configure how it behaves.',
diff --git a/packages/cli/assets/docs/tree/check-the-props.doc.mjs b/packages/cli/assets/docs/tree/check-the-props.doc.mjs
index fb2d63f656..4cfeac2dbe 100644
--- a/packages/cli/assets/docs/tree/check-the-props.doc.mjs
+++ b/packages/cli/assets/docs/tree/check-the-props.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/check-the-props`:
+ * @file `astryx docs authoring/building-blocks/components/describe-the-component/check-the-props`:
* compare each component doc's props table with the component's TypeScript
* props, read each finding, and fix the doc or the code.
*/
diff --git a/packages/cli/assets/docs/tree/check-your-docs.doc.mjs b/packages/cli/assets/docs/tree/check-your-docs.doc.mjs
index bf8dfa84f5..61a4b9efc3 100644
--- a/packages/cli/assets/docs/tree/check-your-docs.doc.mjs
+++ b/packages/cli/assets/docs/tree/check-your-docs.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/docs/check-your-docs`:
+ * @file `astryx docs authoring/building-blocks/docs/check-your-docs`:
* what each check proves about an integration's docs: the docs check, each
* doc's fields, the read size, and the CLI peer.
*/
@@ -133,7 +133,7 @@ fix: Remove \`summary\`: SingleComponentDoc has no field \`summary\`.`,
"The folder decides the type: `ComponentDoc` in your components root, `IntegrationTemplateDoc` in your templates root, `ThemeDoc` in your themes root, and in your docs root the type the doc's `type` names. Keep the `@type` comment above each doc's export too, so your editor shows the same problems as you type.",
'Every finding is a warning, so the exit code stays 0. With `--json`, they are in `data.docTypes.findings`.',
'It uses the `typescript` your package installs. Where `typescript` is missing or has no JavaScript compiler API, as TypeScript 7 does, it uses `@typescript/typescript6`, the TypeScript 6 API package, if your package installs it. Without either, it prints `[skip] Docs not type-checked` and the reason.',
- 'Every field of every doc type is in {@link generic:authoring}.',
+ 'Every field of every doc type is in {@link generic:field-reference}.',
],
},
],
diff --git a/packages/cli/assets/docs/tree/checks.doc.mjs b/packages/cli/assets/docs/tree/checks.doc.mjs
index bb744b9ea4..37c2d0d208 100644
--- a/packages/cli/assets/docs/tree/checks.doc.mjs
+++ b/packages/cli/assets/docs/tree/checks.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/ship/checks`: what each package check
+ * @file `astryx docs authoring/ship/checks`: what each package check
* proves, what fails and what only warns, and one command to run them all.
*/
diff --git a/packages/cli/assets/docs/tree/cli-command.doc.mjs b/packages/cli/assets/docs/tree/cli-command.doc.mjs
index fda721f78c..14b449efa3 100644
--- a/packages/cli/assets/docs/tree/cli-command.doc.mjs
+++ b/packages/cli/assets/docs/tree/cli-command.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/configuration/cli-command`:
+ * @file `astryx docs authoring/building-blocks/configuration/cli-command`:
* name the command an integration's users run the CLI with, so every command
* the CLI prints in their apps starts with it.
*/
diff --git a/packages/cli/assets/docs/tree/cli.doc.mjs b/packages/cli/assets/docs/tree/cli.doc.mjs
index 21279b192f..c541672fd3 100644
--- a/packages/cli/assets/docs/tree/cli.doc.mjs
+++ b/packages/cli/assets/docs/tree/cli.doc.mjs
@@ -14,7 +14,7 @@ export const docs = {
name: 'cli',
title: 'Astryx CLI',
summary:
- 'Commands, programmatic APIs, integration authoring, and output contracts.',
+ 'Commands, programmatic APIs, and output contracts. Building an integration is under {@link namespace:authoring}.',
keywords: ['cli', 'commands', 'api', 'reference'],
slots: {
guides: {title: 'Guides', accepts: {kinds: ['generic', 'namespace']}},
diff --git a/packages/cli/assets/docs/tree/codemods.doc.mjs b/packages/cli/assets/docs/tree/codemods.doc.mjs
index de4fcd48a1..71a8278de1 100644
--- a/packages/cli/assets/docs/tree/codemods.doc.mjs
+++ b/packages/cli/assets/docs/tree/codemods.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/codemods`: add codemods to an
+ * @file `astryx docs authoring/building-blocks/codemods`: add codemods to an
* integration package, and know which of them `astryx upgrade` runs in an app.
*/
diff --git a/packages/cli/assets/docs/tree/component-family.doc.mjs b/packages/cli/assets/docs/tree/component-family.doc.mjs
index 440fce1832..9921ec8490 100644
--- a/packages/cli/assets/docs/tree/component-family.doc.mjs
+++ b/packages/cli/assets/docs/tree/component-family.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/component-family`:
+ * @file `astryx docs authoring/building-blocks/components/describe-the-component/component-family`:
* author one ComponentDoc for several public exports in a component family.
*/
diff --git a/packages/cli/assets/docs/tree/component-imports.doc.mjs b/packages/cli/assets/docs/tree/component-imports.doc.mjs
index 016a835d5d..221ebde386 100644
--- a/packages/cli/assets/docs/tree/component-imports.doc.mjs
+++ b/packages/cli/assets/docs/tree/component-imports.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/components/component-imports`: make an
+ * @file `astryx docs authoring/building-blocks/components/component-imports`: make an
* integration component's documented import resolve from the packed package.
*/
diff --git a/packages/cli/assets/docs/tree/components.doc.mjs b/packages/cli/assets/docs/tree/components.doc.mjs
index 8dd93cd8e7..d5b38881f4 100644
--- a/packages/cli/assets/docs/tree/components.doc.mjs
+++ b/packages/cli/assets/docs/tree/components.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/components`: guides for adding and
+ * @file `astryx docs authoring/building-blocks/components`: guides for adding and
* documenting components in an integration package.
*/
diff --git a/packages/cli/assets/docs/tree/configuration.doc.mjs b/packages/cli/assets/docs/tree/configuration.doc.mjs
index 4b58452f5f..d912b18e6f 100644
--- a/packages/cli/assets/docs/tree/configuration.doc.mjs
+++ b/packages/cli/assets/docs/tree/configuration.doc.mjs
@@ -1,6 +1,6 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-/** @file astryx docs cli/integrations/building-blocks/configuration — set how your integration behaves. */
+/** @file astryx docs authoring/building-blocks/configuration — set how your integration behaves. */
/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
export const docs = {
diff --git a/packages/cli/assets/docs/tree/debug-and-gap-reports.doc.mjs b/packages/cli/assets/docs/tree/debug-and-gap-reports.doc.mjs
index fe531be76f..643e9d281d 100644
--- a/packages/cli/assets/docs/tree/debug-and-gap-reports.doc.mjs
+++ b/packages/cli/assets/docs/tree/debug-and-gap-reports.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/configuration/debug-and-gap-reports`: receive a record
+ * @file `astryx docs authoring/building-blocks/configuration/debug-and-gap-reports`: receive a record
* of each CLI run with `debug`, and handle `astryx gap-report` with
* `gapReport`, both named exports of the integration manifest.
*/
diff --git a/packages/cli/assets/docs/tree/define-the-theme.doc.mjs b/packages/cli/assets/docs/tree/define-the-theme.doc.mjs
index dc5f30c500..90f2715862 100644
--- a/packages/cli/assets/docs/tree/define-the-theme.doc.mjs
+++ b/packages/cli/assets/docs/tree/define-the-theme.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/themes/define-the-theme`:
+ * @file `astryx docs authoring/building-blocks/themes/define-the-theme`:
* map the palette to tokens, keep light-dark() to colors, and avoid Core internals.
*/
diff --git a/packages/cli/assets/docs/tree/describe-the-component.doc.mjs b/packages/cli/assets/docs/tree/describe-the-component.doc.mjs
index c7076e8915..3e7a5ceb88 100644
--- a/packages/cli/assets/docs/tree/describe-the-component.doc.mjs
+++ b/packages/cli/assets/docs/tree/describe-the-component.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component`:
+ * @file `astryx docs authoring/building-blocks/components/describe-the-component`:
* choose and maintain the ComponentDoc shape that matches a component's public
* source.
*/
diff --git a/packages/cli/assets/docs/tree/docs.doc.mjs b/packages/cli/assets/docs/tree/docs.doc.mjs
index 5174a591ef..e7984c9286 100644
--- a/packages/cli/assets/docs/tree/docs.doc.mjs
+++ b/packages/cli/assets/docs/tree/docs.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/docs`: the guides to
+ * @file `astryx docs authoring/building-blocks/docs`: the guides to
* writing docs for an integration package, which join the same docs tree as
* the CLI's own (spec:AST-046, spec:AST-047).
*/
diff --git a/packages/cli/assets/docs/tree/document-the-template.doc.mjs b/packages/cli/assets/docs/tree/document-the-template.doc.mjs
index 69913bda74..e51dcfef1c 100644
--- a/packages/cli/assets/docs/tree/document-the-template.doc.mjs
+++ b/packages/cli/assets/docs/tree/document-the-template.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template`:
+ * @file `astryx docs authoring/building-blocks/templates/document-the-template`:
* document page and block templates for discovery and correct reuse.
*/
diff --git a/packages/cli/assets/docs/tree/document-the-theme.doc.mjs b/packages/cli/assets/docs/tree/document-the-theme.doc.mjs
index 577e3ab449..e178de483d 100644
--- a/packages/cli/assets/docs/tree/document-the-theme.doc.mjs
+++ b/packages/cli/assets/docs/tree/document-the-theme.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/themes/document-the-theme`:
+ * @file `astryx docs authoring/building-blocks/themes/document-the-theme`:
* document a theme by extending the core theme topic, not in agent guidance.
*/
diff --git a/packages/cli/assets/docs/tree/export-template-assets.doc.mjs b/packages/cli/assets/docs/tree/export-template-assets.doc.mjs
index 687ee4136e..04bd034f39 100644
--- a/packages/cli/assets/docs/tree/export-template-assets.doc.mjs
+++ b/packages/cli/assets/docs/tree/export-template-assets.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/export-template-assets`:
+ * @file `astryx docs authoring/building-blocks/templates/build-the-template/package-and-test/export-template-assets`:
* expose and include everything a copied template imports, and declare the
* packages it needs.
*/
diff --git a/packages/cli/assets/docs/tree/extend-or-replace.doc.mjs b/packages/cli/assets/docs/tree/extend-or-replace.doc.mjs
index cdf5b53d2a..fc45c193ce 100644
--- a/packages/cli/assets/docs/tree/extend-or-replace.doc.mjs
+++ b/packages/cli/assets/docs/tree/extend-or-replace.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/docs/extend-or-replace`:
+ * @file `astryx docs authoring/building-blocks/docs/extend-or-replace`:
* take over an existing topic with `replaces`, merge sections into one with
* `extends`, and check overlaps with Core topics.
*/
diff --git a/packages/cli/assets/docs/authoring.doc.mjs b/packages/cli/assets/docs/tree/field-reference.doc.mjs
similarity index 56%
rename from packages/cli/assets/docs/authoring.doc.mjs
rename to packages/cli/assets/docs/tree/field-reference.doc.mjs
index 83177a3393..01c34a2e3b 100644
--- a/packages/cli/assets/docs/authoring.doc.mjs
+++ b/packages/cli/assets/docs/tree/field-reference.doc.mjs
@@ -1,14 +1,15 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs authoring`: every authoring schema, one section each.
+ * @file `astryx docs authoring/field-reference`: every authoring schema, one
+ * section each. `astryx docs authoring <name>` reads one of them.
*
* Built from the self-docs colocated under packages/cli/authoring, so it cannot
* drift from the schemas it describes. `astryx doctor` names a self-doc this
- * topic cannot reach.
+ * guide cannot reach.
*/
-import {buildAuthoringTopic} from '../../foundation/discovery/authoring-self-docs.mjs';
+import {buildAuthoringTopic} from '../../../foundation/discovery/authoring-self-docs.mjs';
/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
export const docs = await buildAuthoringTopic();
diff --git a/packages/cli/assets/docs/tree/fonts-and-assets.doc.mjs b/packages/cli/assets/docs/tree/fonts-and-assets.doc.mjs
index 81f5a55d33..1a602f3255 100644
--- a/packages/cli/assets/docs/tree/fonts-and-assets.doc.mjs
+++ b/packages/cli/assets/docs/tree/fonts-and-assets.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/themes/fonts-and-assets`:
+ * @file `astryx docs authoring/building-blocks/themes/fonts-and-assets`:
* ship a theme's optional font loader beside its built module and CSS.
*/
diff --git a/packages/cli/assets/docs/tree/generate-a-palette.doc.mjs b/packages/cli/assets/docs/tree/generate-a-palette.doc.mjs
index 47ebc55367..346d7c316c 100644
--- a/packages/cli/assets/docs/tree/generate-a-palette.doc.mjs
+++ b/packages/cli/assets/docs/tree/generate-a-palette.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/themes/generate-a-palette`:
+ * @file `astryx docs authoring/building-blocks/themes/generate-a-palette`:
* turn a few seed colors into a full light and dark color palette.
*/
diff --git a/packages/cli/assets/docs/tree/global-integrations.doc.mjs b/packages/cli/assets/docs/tree/global-integrations.doc.mjs
index 340088a2d5..3f07b2d42e 100644
--- a/packages/cli/assets/docs/tree/global-integrations.doc.mjs
+++ b/packages/cli/assets/docs/tree/global-integrations.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/global-integrations`: make an
+ * @file `astryx docs authoring/global-integrations`: make an
* integration work when people install it next to their global Astryx
* install; a checklist and the commands to try it (spec AST-081 FR12).
*/
@@ -11,7 +11,7 @@ export const docs = {
type: 'generic',
name: 'global-integrations',
placement: {
- parent: 'namespace:integrations',
+ parent: 'namespace:authoring',
slot: 'guides',
order: 25,
},
diff --git a/packages/cli/assets/docs/tree/grade-template-with-agent.doc.mjs b/packages/cli/assets/docs/tree/grade-template-with-agent.doc.mjs
index 99fdb1b946..9a4e23b4d4 100644
--- a/packages/cli/assets/docs/tree/grade-template-with-agent.doc.mjs
+++ b/packages/cli/assets/docs/tree/grade-template-with-agent.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/write-good-templates/grade-template-with-agent`:
+ * @file `astryx docs authoring/building-blocks/templates/write-good-templates/grade-template-with-agent`:
* give an agent the canonical rubric and require a reproducible template grade.
*/
@@ -36,11 +36,11 @@ export const docs = {
code: `Grade integration template <id> from <package> at <revision>.
Before scoring:
-1. Read \`astryx docs cli/integrations/building-blocks/templates/write-good-templates --full\`.
-2. Read \`astryx docs cli/integrations/building-blocks/templates/write-good-templates/template-grading-rubric --full\` and every guide it links.
+1. Read \`astryx docs authoring/building-blocks/templates/write-good-templates --full\`.
+2. Read \`astryx docs authoring/building-blocks/templates/write-good-templates/template-grading-rubric --full\` and every guide it links.
3. Inspect the template source, its matching .doc.mjs file, package.json exports and files, and astryx.integration.mjs.
4. Run \`astryx integration verify\` in the package.
-5. Follow \`astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/test-template-in-app --full\`: install the packed package in the clean app, copy the template, build the app, and render the behavior matrix.
+5. Follow \`astryx docs authoring/building-blocks/templates/build-the-template/package-and-test/test-template-in-app --full\`: install the packed package in the clean app, copy the template, build the app, and render the behavior matrix.
Score all seven rubric categories. Cite file and line evidence for every deduction. Do not award points for a state you did not inspect. If browser or build evidence is unavailable, say so and mark the template not publishable.
diff --git a/packages/cli/assets/docs/tree/help.doc.mjs b/packages/cli/assets/docs/tree/help.doc.mjs
index b78aeb0310..595c264b97 100644
--- a/packages/cli/assets/docs/tree/help.doc.mjs
+++ b/packages/cli/assets/docs/tree/help.doc.mjs
@@ -1,12 +1,12 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-/** @file astryx docs cli/integrations/help — find a CLI message and its fix. */
+/** @file astryx docs authoring/help — find a CLI message and its fix. */
/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
export const docs = {
type: 'namespace',
name: 'help',
- placement: {parent: 'namespace:integrations', slot: 'guides', order: 40},
+ placement: {parent: 'namespace:authoring', slot: 'guides', order: 40},
title: 'Help',
summary: 'Find a CLI message and how to fix it.',
keywords: ['help', 'troubleshooting', 'error'],
diff --git a/packages/cli/assets/docs/tree/links.doc.mjs b/packages/cli/assets/docs/tree/links.doc.mjs
index 5a6611ea07..ea6412c77d 100644
--- a/packages/cli/assets/docs/tree/links.doc.mjs
+++ b/packages/cli/assets/docs/tree/links.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/docs/links`: link one doc
+ * @file `astryx docs authoring/building-blocks/docs/links`: link one doc
* to another by identity, link the CLI's docs, and fix a link that names no
* doc.
*/
diff --git a/packages/cli/assets/docs/tree/package-and-test.doc.mjs b/packages/cli/assets/docs/tree/package-and-test.doc.mjs
index e9966a5fae..831c2c2bec 100644
--- a/packages/cli/assets/docs/tree/package-and-test.doc.mjs
+++ b/packages/cli/assets/docs/tree/package-and-test.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test`:
+ * @file `astryx docs authoring/building-blocks/templates/build-the-template/package-and-test`:
* expose a template from its package and prove the copied result in an app.
*/
diff --git a/packages/cli/assets/docs/tree/page-template.doc.mjs b/packages/cli/assets/docs/tree/page-template.doc.mjs
index f455546977..7080638e4a 100644
--- a/packages/cli/assets/docs/tree/page-template.doc.mjs
+++ b/packages/cli/assets/docs/tree/page-template.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template/page-template`:
+ * @file `astryx docs authoring/building-blocks/templates/document-the-template/page-template`:
* the page-only fields that help people find a page.
*/
diff --git a/packages/cli/assets/docs/tree/publishing.doc.mjs b/packages/cli/assets/docs/tree/publishing.doc.mjs
index 1a95eab262..7d705412b5 100644
--- a/packages/cli/assets/docs/tree/publishing.doc.mjs
+++ b/packages/cli/assets/docs/tree/publishing.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/ship/publishing`: publish an integration to
+ * @file `astryx docs authoring/ship/publishing`: publish an integration to
* npm, use release tags, and check the package before and after.
*/
diff --git a/packages/cli/assets/docs/tree/quick-start.doc.mjs b/packages/cli/assets/docs/tree/quick-start.doc.mjs
index 7eaae541da..707ed8e915 100644
--- a/packages/cli/assets/docs/tree/quick-start.doc.mjs
+++ b/packages/cli/assets/docs/tree/quick-start.doc.mjs
@@ -5,7 +5,7 @@ export const docs = {
type: 'generic',
name: 'quick-start',
placement: {
- parent: 'namespace:integrations',
+ parent: 'namespace:authoring',
slot: 'guides',
order: 10,
},
diff --git a/packages/cli/assets/docs/tree/replace-a-core-component.doc.mjs b/packages/cli/assets/docs/tree/replace-a-core-component.doc.mjs
index 0d8a521bc8..0e85f5f568 100644
--- a/packages/cli/assets/docs/tree/replace-a-core-component.doc.mjs
+++ b/packages/cli/assets/docs/tree/replace-a-core-component.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/components/replace-a-core-component`:
+ * @file `astryx docs authoring/building-blocks/components/replace-a-core-component`:
* intentionally make an integration component the default for a Core identity.
*/
diff --git a/packages/cli/assets/docs/tree/replace-a-core-template.doc.mjs b/packages/cli/assets/docs/tree/replace-a-core-template.doc.mjs
index d955056305..811a4a694c 100644
--- a/packages/cli/assets/docs/tree/replace-a-core-template.doc.mjs
+++ b/packages/cli/assets/docs/tree/replace-a-core-template.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template/replace-a-core-template`:
+ * @file `astryx docs authoring/building-blocks/templates/document-the-template/replace-a-core-template`:
* deliberately replace one Core template through template metadata.
*/
diff --git a/packages/cli/assets/docs/tree/sections-and-placement.doc.mjs b/packages/cli/assets/docs/tree/sections-and-placement.doc.mjs
index cb18d0dbf6..a4187ee47b 100644
--- a/packages/cli/assets/docs/tree/sections-and-placement.doc.mjs
+++ b/packages/cli/assets/docs/tree/sections-and-placement.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/docs/sections-and-placement`:
+ * @file `astryx docs authoring/building-blocks/docs/sections-and-placement`:
* give an integration package its own section in the docs tree, place guides
* in it, and fix a placement that fails.
*/
diff --git a/packages/cli/assets/docs/tree/see-it-in-an-app.doc.mjs b/packages/cli/assets/docs/tree/see-it-in-an-app.doc.mjs
index f64c9fdc3f..5b6aaa35e6 100644
--- a/packages/cli/assets/docs/tree/see-it-in-an-app.doc.mjs
+++ b/packages/cli/assets/docs/tree/see-it-in-an-app.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/components/see-it-in-an-app`: inspect an
+ * @file `astryx docs authoring/building-blocks/components/see-it-in-an-app`: inspect an
* integration component from an app that installs the package.
*/
diff --git a/packages/cli/assets/docs/tree/ship.doc.mjs b/packages/cli/assets/docs/tree/ship.doc.mjs
index 13bdf2fcbe..888e284289 100644
--- a/packages/cli/assets/docs/tree/ship.doc.mjs
+++ b/packages/cli/assets/docs/tree/ship.doc.mjs
@@ -1,12 +1,12 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-/** @file astryx docs cli/integrations/ship — test, publish, and upgrade. */
+/** @file astryx docs authoring/ship — test, publish, and upgrade. */
/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
export const docs = {
type: 'namespace',
name: 'ship',
- placement: {parent: 'namespace:integrations', slot: 'guides', order: 30},
+ placement: {parent: 'namespace:authoring', slot: 'guides', order: 30},
title: 'Ship',
summary: 'Test, publish, and upgrade your package.',
keywords: ['ship', 'publish', 'release', 'upgrade'],
diff --git a/packages/cli/assets/docs/tree/short-and-findable.doc.mjs b/packages/cli/assets/docs/tree/short-and-findable.doc.mjs
index 3241753599..1784a6dfe9 100644
--- a/packages/cli/assets/docs/tree/short-and-findable.doc.mjs
+++ b/packages/cli/assets/docs/tree/short-and-findable.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/docs/short-and-findable`:
+ * @file `astryx docs authoring/building-blocks/docs/short-and-findable`:
* keep each read short, lead each section with its summary, and write docs
* that search finds.
*/
diff --git a/packages/cli/assets/docs/tree/single-component.doc.mjs b/packages/cli/assets/docs/tree/single-component.doc.mjs
index 83be60e434..67f90988c3 100644
--- a/packages/cli/assets/docs/tree/single-component.doc.mjs
+++ b/packages/cli/assets/docs/tree/single-component.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/single-component`:
+ * @file `astryx docs authoring/building-blocks/components/describe-the-component/single-component`:
* write and maintain the default ComponentDoc for one public component.
*/
diff --git a/packages/cli/assets/docs/tree/start-a-template.doc.mjs b/packages/cli/assets/docs/tree/start-a-template.doc.mjs
index dc38f33bef..6da53a1af1 100644
--- a/packages/cli/assets/docs/tree/start-a-template.doc.mjs
+++ b/packages/cli/assets/docs/tree/start-a-template.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/start-a-template`:
+ * @file `astryx docs authoring/building-blocks/templates/start-a-template`:
* what a template is, why an integration shares one, whether it is a page or
* a block, and how to add one.
*/
diff --git a/packages/cli/assets/docs/tree/subcomponent.doc.mjs b/packages/cli/assets/docs/tree/subcomponent.doc.mjs
index 7b9deb98c4..73576c122d 100644
--- a/packages/cli/assets/docs/tree/subcomponent.doc.mjs
+++ b/packages/cli/assets/docs/tree/subcomponent.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/components/describe-the-component/subcomponent`:
+ * @file `astryx docs authoring/building-blocks/components/describe-the-component/subcomponent`:
* give one member of a component family its own ComponentDoc.
*/
diff --git a/packages/cli/assets/docs/tree/template-assets.doc.mjs b/packages/cli/assets/docs/tree/template-assets.doc.mjs
index 003de0be06..1d3f752778 100644
--- a/packages/cli/assets/docs/tree/template-assets.doc.mjs
+++ b/packages/cli/assets/docs/tree/template-assets.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets`:
+ * @file `astryx docs authoring/building-blocks/templates/build-the-template/template-assets`:
* make every style, font, icon, and media dependency survive a template copy.
*/
diff --git a/packages/cli/assets/docs/tree/template-doc-overview.doc.mjs b/packages/cli/assets/docs/tree/template-doc-overview.doc.mjs
index 3f82278f68..ac533e82d1 100644
--- a/packages/cli/assets/docs/tree/template-doc-overview.doc.mjs
+++ b/packages/cli/assets/docs/tree/template-doc-overview.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template/template-doc-overview`:
+ * @file `astryx docs authoring/building-blocks/templates/document-the-template/template-doc-overview`:
* the source and doc file pair, the fields every template doc shares, and how
* to check what Astryx lists.
*/
@@ -67,7 +67,7 @@ export const docs = {
'Set `type` to the kind you chose in {@link generic:start-a-template}. It decides which other fields the doc accepts.',
'The file name sets the template id ({@link generic:start-a-template}). Labels live in the doc: the terminal list prints `name`, and JSON listings print `displayName`. Changing either never changes the id.',
'Write the description for someone choosing between templates. The Doc metadata category in {@link generic:template-grading-rubric} defines what a complete description covers.',
- "Name the ideas the template serves in `keywords`: the domains, tasks, and other names a builder might use for it, in lowercase, such as `['monitoring', 'uptime', 'on-call']` for a service-health dashboard. How search and build use them is in {@link generic:authoring}, so the description can stay about the layout.",
+ "Name the ideas the template serves in `keywords`: the domains, tasks, and other names a builder might use for it, in lowercase, such as `['monitoring', 'uptime', 'on-call']` for a service-health dashboard. How search and build use them is in {@link generic:field-reference}, so the description can stay about the layout.",
'Add `isReady: false` as soon as you generate the doc, because a doc without `isReady` is listed as ready. Keep it until the template passes {@link generic:test-template-in-app} and the quality review.',
],
},
diff --git a/packages/cli/assets/docs/tree/template-fonts.doc.mjs b/packages/cli/assets/docs/tree/template-fonts.doc.mjs
index 63de6f0915..271b919d63 100644
--- a/packages/cli/assets/docs/tree/template-fonts.doc.mjs
+++ b/packages/cli/assets/docs/tree/template-fonts.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-fonts`:
+ * @file `astryx docs authoring/building-blocks/templates/build-the-template/template-assets/template-fonts`:
* use the app typeface by default, and ship every font file a template needs
* when it must bring its own.
*/
diff --git a/packages/cli/assets/docs/tree/template-grading-rubric.doc.mjs b/packages/cli/assets/docs/tree/template-grading-rubric.doc.mjs
index 8a7ef05a65..561f4758c0 100644
--- a/packages/cli/assets/docs/tree/template-grading-rubric.doc.mjs
+++ b/packages/cli/assets/docs/tree/template-grading-rubric.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/templates/template-grading-rubric`:
+ * @file `astryx docs authoring/templates/template-grading-rubric`:
* complete scoring rules for page and block template quality.
*/
diff --git a/packages/cli/assets/docs/tree/template-icons.doc.mjs b/packages/cli/assets/docs/tree/template-icons.doc.mjs
index 6da3f52e46..ef27f28dca 100644
--- a/packages/cli/assets/docs/tree/template-icons.doc.mjs
+++ b/packages/cli/assets/docs/tree/template-icons.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-icons`:
+ * @file `astryx docs authoring/building-blocks/templates/build-the-template/template-assets/template-icons`:
* render template icons through Astryx and ship custom product icons from the
* package.
*/
diff --git a/packages/cli/assets/docs/tree/template-images-media.doc.mjs b/packages/cli/assets/docs/tree/template-images-media.doc.mjs
index 75b375126a..c582066650 100644
--- a/packages/cli/assets/docs/tree/template-images-media.doc.mjs
+++ b/packages/cli/assets/docs/tree/template-images-media.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-images-media`:
+ * @file `astryx docs authoring/building-blocks/templates/build-the-template/template-assets/template-images-media`:
* keep template images and video working after the copy, or make them clear
* placeholders.
*/
diff --git a/packages/cli/assets/docs/tree/template-styles.doc.mjs b/packages/cli/assets/docs/tree/template-styles.doc.mjs
index 032b33464e..31b53532df 100644
--- a/packages/cli/assets/docs/tree/template-styles.doc.mjs
+++ b/packages/cli/assets/docs/tree/template-styles.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/template-assets/template-styles`:
+ * @file `astryx docs authoring/building-blocks/templates/build-the-template/template-assets/template-styles`:
* style a template with Astryx first, keep editable styles in the file, and
* ship shared CSS from the package.
*/
diff --git a/packages/cli/assets/docs/tree/templates.doc.mjs b/packages/cli/assets/docs/tree/templates.doc.mjs
index 17325e19e1..e573b3c957 100644
--- a/packages/cli/assets/docs/tree/templates.doc.mjs
+++ b/packages/cli/assets/docs/tree/templates.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates`: guides for adding,
+ * @file `astryx docs authoring/building-blocks/templates`: guides for adding,
* documenting, packaging, and testing templates in an integration package.
*/
diff --git a/packages/cli/assets/docs/tree/test-in-an-app.doc.mjs b/packages/cli/assets/docs/tree/test-in-an-app.doc.mjs
index 185b557d68..da4c8795ba 100644
--- a/packages/cli/assets/docs/tree/test-in-an-app.doc.mjs
+++ b/packages/cli/assets/docs/tree/test-in-an-app.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/ship/test-in-an-app`: install the packed
+ * @file `astryx docs authoring/ship/test-in-an-app`: install the packed
* package in an app and run the commands its users run.
*/
diff --git a/packages/cli/assets/docs/tree/test-template-in-app.doc.mjs b/packages/cli/assets/docs/tree/test-template-in-app.doc.mjs
index c61d2be148..f6ddc4d6c7 100644
--- a/packages/cli/assets/docs/tree/test-template-in-app.doc.mjs
+++ b/packages/cli/assets/docs/tree/test-template-in-app.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/test-template-in-app`:
+ * @file `astryx docs authoring/building-blocks/templates/build-the-template/package-and-test/test-template-in-app`:
* copy the packed template into a clean app, build it, and render it the way
* apps will.
*/
diff --git a/packages/cli/assets/docs/tree/themes.doc.mjs b/packages/cli/assets/docs/tree/themes.doc.mjs
index 237d21d5c6..03ac12c5a4 100644
--- a/packages/cli/assets/docs/tree/themes.doc.mjs
+++ b/packages/cli/assets/docs/tree/themes.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/themes`: author a theme
+ * @file `astryx docs authoring/building-blocks/themes`: author a theme
* in an integration; apps install, apply, and extend it like any theme.
*/
diff --git a/packages/cli/assets/docs/tree/troubleshooting.doc.mjs b/packages/cli/assets/docs/tree/troubleshooting.doc.mjs
index 6e670ae99a..4a143f76e4 100644
--- a/packages/cli/assets/docs/tree/troubleshooting.doc.mjs
+++ b/packages/cli/assets/docs/tree/troubleshooting.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/help/troubleshooting`: the messages the CLI
+ * @file `astryx docs authoring/help/troubleshooting`: the messages the CLI
* prints while you build, verify, and install an integration, and the fix
* for each.
*/
diff --git a/packages/cli/assets/docs/tree/upgrading.doc.mjs b/packages/cli/assets/docs/tree/upgrading.doc.mjs
index 6b5cd357b9..96b972ba21 100644
--- a/packages/cli/assets/docs/tree/upgrading.doc.mjs
+++ b/packages/cli/assets/docs/tree/upgrading.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/ship/upgrading`: update an integration
+ * @file `astryx docs authoring/ship/upgrading`: update an integration
* package for each Astryx release, and the command apps run to upgrade with
* it.
*/
diff --git a/packages/cli/assets/docs/tree/use-a-theme-in-an-app.doc.mjs b/packages/cli/assets/docs/tree/use-a-theme-in-an-app.doc.mjs
index 1d3541ba99..b5d1d5bde6 100644
--- a/packages/cli/assets/docs/tree/use-a-theme-in-an-app.doc.mjs
+++ b/packages/cli/assets/docs/tree/use-a-theme-in-an-app.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/themes/use-a-theme-in-an-app`:
+ * @file `astryx docs authoring/building-blocks/themes/use-a-theme-in-an-app`:
* an app installs the integration and applies or extends the theme, like any theme.
*/
diff --git a/packages/cli/assets/docs/tree/verify-packed-template.doc.mjs b/packages/cli/assets/docs/tree/verify-packed-template.doc.mjs
index db795c6b92..cc57781f91 100644
--- a/packages/cli/assets/docs/tree/verify-packed-template.doc.mjs
+++ b/packages/cli/assets/docs/tree/verify-packed-template.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/verify-packed-template`:
+ * @file `astryx docs authoring/building-blocks/templates/build-the-template/package-and-test/verify-packed-template`:
* what `integration verify` checks for templates, and what it leaves to the
* app test.
*/
diff --git a/packages/cli/assets/docs/tree/versioning.doc.mjs b/packages/cli/assets/docs/tree/versioning.doc.mjs
index 4c63ad41d9..d45cbc60eb 100644
--- a/packages/cli/assets/docs/tree/versioning.doc.mjs
+++ b/packages/cli/assets/docs/tree/versioning.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/ship/versioning`: version an integration
+ * @file `astryx docs authoring/ship/versioning`: version an integration
* package, know which changes break apps, declare peer ranges, keep apps on
* older CLIs working, and match codemod folders to versions.
*/
diff --git a/packages/cli/assets/docs/tree/write-good-templates.doc.mjs b/packages/cli/assets/docs/tree/write-good-templates.doc.mjs
index 52e1eff0c9..ebf6b3d73e 100644
--- a/packages/cli/assets/docs/tree/write-good-templates.doc.mjs
+++ b/packages/cli/assets/docs/tree/write-good-templates.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/write-good-templates`:
+ * @file `astryx docs authoring/building-blocks/templates/write-good-templates`:
* what makes a template good, the rubric that scores it, and grading with an agent.
*/
diff --git a/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs b/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs
index 9869d2fc3d..f7593e7cd0 100644
--- a/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs
+++ b/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/write-the-template-file`:
+ * @file `astryx docs authoring/building-blocks/templates/build-the-template/write-the-template-file`:
* what gets copied, where the copied file lands, and the imports and
* export a copied template needs.
*/
diff --git a/packages/cli/authoring/doctypes/schema/schema.doc.mjs b/packages/cli/authoring/doctypes/schema/schema.doc.mjs
index 6784f6f57d..54e0683cb0 100644
--- a/packages/cli/authoring/doctypes/schema/schema.doc.mjs
+++ b/packages/cli/authoring/doctypes/schema/schema.doc.mjs
@@ -49,7 +49,7 @@ export const doc = {
name: 'namespace',
type: 'string',
description:
- "The group that reads this doc: 'authoring' for a file an author writes (a section of {@link generic:authoring}), or 'cli/api' for a shape the CLI returns (the docs tree adopts it by kind, as the leaf `cli/api/schemas/<name>`). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
+ "The group that reads this doc: 'authoring' for a file an author writes (a section of {@link generic:field-reference}), or 'cli/api' for a shape the CLI returns (the docs tree adopts it by kind, as the leaf `cli/api/schemas/<name>`). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
},
{
name: 'aliases',
diff --git a/packages/cli/authoring/integration/integration.doc.mjs b/packages/cli/authoring/integration/integration.doc.mjs
index e71dba6ce5..4932e23df4 100644
--- a/packages/cli/authoring/integration/integration.doc.mjs
+++ b/packages/cli/authoring/integration/integration.doc.mjs
@@ -131,7 +131,7 @@ export const doc = {
},
{
type: 'prose',
- text: "Set `cliCommand` only when your users run the CLI with a command other than their package manager's, such as `acme astryx`. The CLI picks the command it prints in this order: the `cliCommand` of the loaded integrations when they name one command, then the command a host tool names, then the package manager's. Two different `cliCommand` values cancel out, and `astryx doctor` warns in its `cli-command` check. See `astryx docs cli/integrations/building-blocks/configuration/cli-command`.",
+ text: "Set `cliCommand` only when your users run the CLI with a command other than their package manager's, such as `acme astryx`. The CLI picks the command it prints in this order: the `cliCommand` of the loaded integrations when they name one command, then the command a host tool names, then the package manager's. Two different `cliCommand` values cancel out, and `astryx doctor` warns in its `cli-command` check. See `astryx docs authoring/building-blocks/configuration/cli-command`.",
},
{
type: 'prose',
diff --git a/packages/cli/authoring/integration/type.ts b/packages/cli/authoring/integration/type.ts
index 4cf9ed39b4..2740c09a97 100644
--- a/packages/cli/authoring/integration/type.ts
+++ b/packages/cli/authoring/integration/type.ts
@@ -11,7 +11,7 @@
* The manifest module may also carry `debug` and `gapReport` NAMED exports.
* They are not fields here on purpose: a CLI released before a given manifest
* field existed could reject it and lose every contribution, while an unknown
- * named export is simply not read. See `astryx docs cli/integrations`.
+ * named export is simply not read. See `astryx docs authoring`.
*/
export interface AstryxIntegration {
/** Stable logical provider ID. Omit to use package.json#name. Set this only
diff --git a/packages/cli/clients/cli/commands/docs.doc.mjs b/packages/cli/clients/cli/commands/docs.doc.mjs
index 011ae8e159..5d4d81683d 100644
--- a/packages/cli/clients/cli/commands/docs.doc.mjs
+++ b/packages/cli/clients/cli/commands/docs.doc.mjs
@@ -58,10 +58,10 @@ export const doc = {
{label: 'Every CLI doc, one line each', cli: 'astryx docs cli --depth all'},
{
label: 'The integration guides as one read',
- cli: 'astryx docs cli/integrations --depth all --detail full',
+ cli: 'astryx docs authoring --depth all --detail full',
},
{label: 'One API function', cli: 'astryx docs cli/api/functions/search'},
- {label: 'A whole guide', cli: 'astryx docs cli/integrations/quick-start --full'},
+ {label: 'A whole guide', cli: 'astryx docs authoring/quick-start --full'},
],
outsideProject: 'same',
exitCodes: [
diff --git a/packages/cli/clients/cli/commands/docs.mjs b/packages/cli/clients/cli/commands/docs.mjs
index 6632a76030..e2ff73d7e8 100644
--- a/packages/cli/clients/cli/commands/docs.mjs
+++ b/packages/cli/clients/cli/commands/docs.mjs
@@ -535,7 +535,7 @@ function emitNode(node, detail, run) {
text(
[
// A child's route is its parent's route and its name, except a flat
- // topic in the Unorganized level, which keeps its own name.
+ // topic in a topic level, which keeps its own name.
node.slots.every(slot =>
slot.children.every(child => child.route.startsWith(`${node.route}/`)),
)
diff --git a/packages/cli/clients/cli/commands/docs.test.mjs b/packages/cli/clients/cli/commands/docs.test.mjs
index 3918bccf72..bd93614292 100644
--- a/packages/cli/clients/cli/commands/docs.test.mjs
+++ b/packages/cli/clients/cli/commands/docs.test.mjs
@@ -227,7 +227,7 @@ describe('the docs tree, one level at a time', () => {
it('wraps namespace summaries without discarding searchable words', async () => {
const {status, stdout} = await runCli([
'docs',
- 'cli/integrations/building-blocks/templates',
+ 'authoring/building-blocks/templates',
]);
expect(status).toBe(0);
expect(stdout).toMatch(/^start-a-template +Help others build apps faster/m);
@@ -274,8 +274,8 @@ describe('the docs tree, one level at a time', () => {
}, SLOW);
it('reads the integration guides by their routes, and not by the old name', async () => {
- // cli/integrations is a namespace: one level, its guides by slot.
- const level = await runCli(['docs', 'cli/integrations']);
+ // authoring is a namespace: one level, its guides by slot.
+ const level = await runCli(['docs', 'authoring']);
expect(level.status).toBe(0);
expect(level.stdout).toMatch(
/^quick-start +Create a new integration package/m,
@@ -283,42 +283,42 @@ describe('the docs tree, one level at a time', () => {
expect(level.stdout).toMatch(/^building-blocks +/m);
const guide = await runCli([
'docs',
- 'cli/integrations/building-blocks/codemods',
+ 'authoring/building-blocks/codemods',
'--index',
]);
expect(guide.status).toBe(0);
expect(guide.stdout).toMatch(
- /Read one section: .*docs cli\/integrations\/building-blocks\/codemods <section>/,
+ /Read one section: .*docs authoring\/building-blocks\/codemods <section>/,
);
// A bare read is one level too: the sections, and how to read it all.
const bare = await runCli([
'docs',
- 'cli/integrations/building-blocks/codemods',
+ 'authoring/building-blocks/codemods',
]);
expect(bare.status).toBe(0);
expect(bare.stdout).toBe(guide.stdout);
expect(bare.stdout).toMatch(
- /Read everything: +.*docs cli\/integrations\/building-blocks\/codemods --full$/m,
+ /Read everything: +.*docs authoring\/building-blocks\/codemods --full$/m,
);
const one = await runCli([
'docs',
- 'cli/integrations/building-blocks/codemods',
+ 'authoring/building-blocks/codemods',
'which-codemods-run',
]);
expect(one.status).toBe(0);
expect(one.stdout).toMatch(/^## Choose when a codemod runs$/m);
expect(one.stdout).toMatch(
- /^Up: .*docs cli\/integrations\/building-blocks\/codemods --index$/m,
+ /^Up: .*docs authoring\/building-blocks\/codemods --index$/m,
);
expect(one.stdout).toMatch(
- /^Previous: .*docs cli\/integrations\/building-blocks\/codemods write-the-transform$/m,
+ /^Previous: .*docs authoring\/building-blocks\/codemods write-the-transform$/m,
);
expect(one.stdout).toMatch(
- /^Next: .*docs cli\/integrations\/building-blocks\/codemods run-codemods-in-an-app$/m,
+ /^Next: .*docs authoring\/building-blocks\/codemods run-codemods-in-an-app$/m,
);
const full = await runCli([
'docs',
- 'cli/integrations/building-blocks/codemods',
+ 'authoring/building-blocks/codemods',
'--full',
]);
expect(full.status).toBe(0);
@@ -343,11 +343,11 @@ describe('the docs tree, one level at a time', () => {
type: 'docs.detail.section',
data: {id: 'side-panels', title: 'Side panels'},
});
- const missing = await runCli(['docs', 'cli', 'zzzz-nope', '--json']);
+ const missing = await runCli(['docs', 'authoring', 'zzzz-nope', '--json']);
expect(missing.status).toBe(1);
const error = JSON.parse(missing.stdout);
expect(error).toMatchObject({code: 'ERR_UNKNOWN_SECTION'});
- expect(error.suggestions.map(s => s.name)).toContain('cli/integrations/quick-start');
+ expect(error.suggestions.map(s => s.name)).toContain('authoring/quick-start');
}, SLOW);
});
diff --git a/packages/cli/clients/cli/commands/integration.doc.mjs b/packages/cli/clients/cli/commands/integration.doc.mjs
index 1259c684db..e94f78c896 100644
--- a/packages/cli/clients/cli/commands/integration.doc.mjs
+++ b/packages/cli/clients/cli/commands/integration.doc.mjs
@@ -8,7 +8,7 @@ export const doc = {
namespace: 'cli/commands',
summary: 'Author and verify an Astryx integration package',
description:
- 'Add contributions to your package, check them on every build with `integration check --strict`, then check the packed package the way an app receives it. The guides start at {@link namespace:integrations}.',
+ 'Add contributions to your package, check them on every build with `integration check --strict`, then check the packed package the way an app receives it. The guides start at {@link namespace:authoring}.',
subcommands: ['add', 'check', 'verify', 'pack'],
examples: [
{
diff --git a/packages/cli/foundation/agent-docs/agent-docs.mjs b/packages/cli/foundation/agent-docs/agent-docs.mjs
index ca5c40622a..700283d6f1 100644
--- a/packages/cli/foundation/agent-docs/agent-docs.mjs
+++ b/packages/cli/foundation/agent-docs/agent-docs.mjs
@@ -824,7 +824,8 @@ export function generateCompressedIndex(
const suffix = resolvedTopics.length > shown.length ? ' …' : '';
lines.push(` docs <topic> ${shown.join(', ')}${suffix} (\`astryx docs\` lists all)`);
}
- lines.push(' docs cli commands, API reference, integration authoring');
+ lines.push(' docs cli commands and API reference');
+ lines.push(' docs authoring build an integration package, and every field it holds');
lines.push(' upgrade --from <old version> --apply run after a dependency bump');
const appendCount = agentDocs.reduce(
(count, contribution) => count + contribution.append.length,
diff --git a/packages/cli/foundation/agent-docs/agent-docs.test.mjs b/packages/cli/foundation/agent-docs/agent-docs.test.mjs
index dae4455872..1176e3847a 100644
--- a/packages/cli/foundation/agent-docs/agent-docs.test.mjs
+++ b/packages/cli/foundation/agent-docs/agent-docs.test.mjs
@@ -209,12 +209,13 @@ describe('generateCompressedIndex', () => {
expect(line).toContain('astryx docs');
});
- it('points to the CLI docs tree on a line of its own', () => {
- // The integration guide lives in the docs tree now (cli/integrations), so
- // the topic line no longer names it; the tree's entry point does.
+ it('points to the CLI docs and the authoring docs on lines of their own', () => {
+ // The integration guides live under `authoring` in the docs tree, so the
+ // topic line does not name them; the tree's entry points do.
const block = generateCompressedIndex('1.0.0');
+ expect(block).toContain(' docs cli commands and API reference');
expect(block).toContain(
- ' docs cli commands, API reference, integration authoring',
+ ' docs authoring build an integration package, and every field it holds',
);
expect(topicLine(block)).not.toContain('cli-integrations');
});
diff --git a/packages/cli/foundation/discovery/authoring-self-docs.mjs b/packages/cli/foundation/discovery/authoring-self-docs.mjs
index 61afe85076..28a0aaf73e 100644
--- a/packages/cli/foundation/discovery/authoring-self-docs.mjs
+++ b/packages/cli/foundation/discovery/authoring-self-docs.mjs
@@ -9,7 +9,7 @@
* `authoring` reference topic with one section per self-doc, and an audit
* naming any self-doc the topic cannot reach, any that fails to load, and any
* section over the docs output budget.
- * @position Read by assets/docs/authoring.doc.mjs (the topic) and by Doctor
+ * @position Read by assets/docs/tree/field-reference.doc.mjs (the guide) and by Doctor
* (the audit). Lives in foundation because authoring/ holds only contracts.
* A new `*.doc.mjs` under authoring/ must be added to the list, or Doctor and
* the self-doc tests fail.
@@ -27,6 +27,15 @@ import {
/** The directory the self-docs live under. */
export const AUTHORING_ROOT = path.join(CLI_ROOT, 'authoring');
+/** The guide that holds every authoring schema, one section each. */
+export const AUTHORING_REFERENCE_NAME = 'field-reference';
+
+/**
+ * Its route. `astryx docs authoring <name>` reads one of its sections through
+ * the authoring namespace (spec:AST-046 FR6).
+ */
+export const AUTHORING_REFERENCE_ROUTE = `authoring/${AUTHORING_REFERENCE_NAME}`;
+
/** Every authoring self-doc, relative to {@link AUTHORING_ROOT}, in reading order. */
export const AUTHORING_SELF_DOCS = [
'integration/integration.doc.mjs',
@@ -189,11 +198,14 @@ export function selfDocSection(doc) {
*/
export function buildAuthoringReferenceDoc(docs) {
return /** @type {any} */ ({
- name: 'authoring',
- title: 'Authoring Reference',
+ type: 'generic',
+ name: AUTHORING_REFERENCE_NAME,
+ placement: {parent: 'namespace:authoring', slot: 'reference', order: 10},
+ title: 'Field reference',
category: 'guide',
+ keywords: ['authoring reference', 'field reference', 'every field'],
description:
- 'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type. The step-by-step guides are under `astryx docs cli/integrations`.',
+ 'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type. The guides that use them are the rest of {@link namespace:authoring}.',
sections: docs.map(selfDocSection),
});
}
diff --git a/packages/cli/foundation/discovery/authoring-self-docs.test.mjs b/packages/cli/foundation/discovery/authoring-self-docs.test.mjs
index 4e6c5860ad..173109b454 100644
--- a/packages/cli/foundation/discovery/authoring-self-docs.test.mjs
+++ b/packages/cli/foundation/discovery/authoring-self-docs.test.mjs
@@ -38,20 +38,32 @@ describe('authoring self-docs', () => {
});
});
- it('builds a valid topic with one section per self-doc', async () => {
- const topic = await buildAuthoringTopic();
+ it('builds a valid guide with one section per self-doc, placed under authoring', async () => {
+ const {placement, ...topic} = await buildAuthoringTopic();
expect(problemsInTopic(topic)).toEqual([]);
expect(topic.sections).toHaveLength(AUTHORING_SELF_DOCS.length);
+ expect(placement).toEqual({
+ parent: 'namespace:authoring',
+ slot: 'reference',
+ order: 10,
+ });
});
it(
'is readable progressively through the docs API',
async () => {
- const index = await docs('authoring', undefined, {index: true});
+ const index = await docs('authoring/field-reference', undefined, {
+ index: true,
+ });
expect(index.type).toBe('docs.index');
expect(index.data.sections.map(s => s.id)).toContain('integration');
+ // The namespace answers a section read from the field reference, as
+ // `astryx docs authoring <name>` always has.
const section = await docs('authoring', 'integration');
expect(section.data.title).toBe('Astryx Integration');
+ expect(
+ (await docs('authoring/field-reference', 'integration')).data,
+ ).toEqual(section.data);
expect(section.data.content.some(block => block.type === 'table')).toBe(
true,
);
diff --git a/packages/cli/foundation/discovery/authoring-surface.mjs b/packages/cli/foundation/discovery/authoring-surface.mjs
index a63108cdfb..c191c2ed34 100644
--- a/packages/cli/foundation/discovery/authoring-surface.mjs
+++ b/packages/cli/foundation/discovery/authoring-surface.mjs
@@ -7,7 +7,7 @@
* @input authoring/index.d.ts and the type modules it re-exports, parsed with
* jscodeshift and never imported or type-checked (consumer installs have no
* TypeScript); the self-docs on disk and in AUTHORING_SELF_DOCS; and the
- * section keys `astryx docs authoring --index` lists.
+ * section keys `astryx docs authoring/field-reference --index` lists.
* @output {@link tracePublicAuthoringTypes}: each exported type and the module
* that declares it. {@link auditAuthoringSurface}: each module whose exported
* types a reader cannot reach and why, each export that cannot be traced,
@@ -424,7 +424,7 @@ function declaredIn(t, folder, name) {
* document something public: a public type declared beside it, and, when its
* title is the name of a type declared beside it, that type.
* @param {{root?: string, sources?: string[], topicKeys?: Set<string> | null}} [options]
- * `topicKeys` are the keys `astryx docs authoring --index` lists; null skips
+ * `topicKeys` are the keys `astryx docs authoring/field-reference --index` lists; null skips
* that comparison.
* @returns {Promise<{
* types: number,
diff --git a/packages/cli/foundation/discovery/authoring-surface.test.mjs b/packages/cli/foundation/discovery/authoring-surface.test.mjs
index 1f20f7e782..d282741afe 100644
--- a/packages/cli/foundation/discovery/authoring-surface.test.mjs
+++ b/packages/cli/foundation/discovery/authoring-surface.test.mjs
@@ -86,7 +86,7 @@ describe('the public authoring surface of this repo', () => {
it(
'audits clean: every exported type has a readable doc and every self-doc documents one',
async () => {
- const index = await docs('authoring', undefined, {index: true});
+ const index = await docs('authoring/field-reference', undefined, {index: true});
const topicKeys = new Set(
index.data.sections.map((/** @type {any} */ s) => s.id),
);
diff --git a/packages/cli/foundation/discovery/cli-self-docs.mjs b/packages/cli/foundation/discovery/cli-self-docs.mjs
index c754f7cb78..4e72bb9e46 100644
--- a/packages/cli/foundation/discovery/cli-self-docs.mjs
+++ b/packages/cli/foundation/discovery/cli-self-docs.mjs
@@ -41,7 +41,8 @@ const NAMESPACED_KINDS = new Set(['command', 'function', 'schema', 'enum']);
/**
* Every namespace a CLI doc may declare, and what reads it. The docs tree
* adopts `cli/commands` (under `cli/commands`) and `cli/api` (under
- * `cli/api/<kind>s`); `astryx docs authoring` reads `authoring` from its list.
+ * `cli/api/<kind>s`); the field reference (`astryx docs authoring/field-reference`)
+ * reads `authoring` from its list.
* @type {Record<string, {reader: 'tree' | 'authoring'}>}
*/
export const CLI_DOC_NAMESPACES = {
@@ -492,13 +493,13 @@ export async function auditCliSelfDocs({
else {
misfiled.push({
source,
- message: `${source} has namespace "authoring", but \`${formatCliCommand('docs authoring')}\` does not list it`,
+ message: `${source} has namespace "authoring", but \`${formatCliCommand('docs authoring/field-reference')}\` does not list it`,
});
}
} else if (inAuthoring) {
misfiled.push({
source,
- message: `${source} is read in \`${formatCliCommand('docs authoring')}\`, but its namespace is "${namespace}"`,
+ message: `${source} is read in \`${formatCliCommand('docs authoring/field-reference')}\`, but its namespace is "${namespace}"`,
});
} else {
treeDocs.push(doc);
diff --git a/packages/cli/foundation/discovery/cli-self-docs.test.mjs b/packages/cli/foundation/discovery/cli-self-docs.test.mjs
index 3131ef4900..33f8bc2892 100644
--- a/packages/cli/foundation/discovery/cli-self-docs.test.mjs
+++ b/packages/cli/foundation/discovery/cli-self-docs.test.mjs
@@ -146,8 +146,8 @@ describe('auditCliSelfDocs', () => {
});
const result = await audit(root, ['y/y.doc.mjs', 'z/z.doc.mjs']);
expect(result.misfiled.map(entry => entry.message)).toEqual([
- `authoring/x/x.doc.mjs has namespace "authoring", but \`${formatCliCommand('docs authoring')}\` does not list it`,
- `authoring/y/y.doc.mjs is read in \`${formatCliCommand('docs authoring')}\`, but its namespace is "cli/api"`,
+ `authoring/x/x.doc.mjs has namespace "authoring", but \`${formatCliCommand('docs authoring/field-reference')}\` does not list it`,
+ `authoring/y/y.doc.mjs is read in \`${formatCliCommand('docs authoring/field-reference')}\`, but its namespace is "cli/api"`,
]);
expect(result.authoring).toBe(1);
expect(result.tree).toBe(0);
diff --git a/packages/cli/foundation/discovery/stray-pointers.test.mjs b/packages/cli/foundation/discovery/stray-pointers.test.mjs
index e0bcce372d..12432ab348 100644
--- a/packages/cli/foundation/discovery/stray-pointers.test.mjs
+++ b/packages/cli/foundation/discovery/stray-pointers.test.mjs
@@ -16,7 +16,7 @@ describe('pointersIn', () => {
it('leaves a walkthrough alone: more words, a flag, or a route', () => {
expect(
pointersIn(
- 'Run `astryx docs theme overview`, `astryx docs --json`, `astryx docs cli/integrations`, or `astryx docs`.',
+ 'Run `astryx docs theme overview`, `astryx docs --json`, `astryx docs authoring/quick-start`, or `astryx docs`.',
),
).toEqual([]);
});
diff --git a/packages/cli/foundation/doc-compiler/split-topic-keywords.test.mjs b/packages/cli/foundation/doc-compiler/split-topic-keywords.test.mjs
index 405a64a36e..4663eb4d07 100644
--- a/packages/cli/foundation/doc-compiler/split-topic-keywords.test.mjs
+++ b/packages/cli/foundation/doc-compiler/split-topic-keywords.test.mjs
@@ -3,7 +3,8 @@
/**
* @file A topic split into a namespace of guides indexes each term once, a
* policy of the docs split itself (no spec clause states it). Below the CLI's own
- * root namespaces (every one but `cli`, its command and API reference), a
+ * root namespaces (every one but `cli`, its command and API reference, and
+ * `authoring`, the integration guides `cli` held before this rule), a
* guide's search keywords are its own: none repeats a keyword its namespace,
* a sibling, or a guide of another split topic declares. A term several
* guides share belongs to their namespace, or to none.
@@ -45,7 +46,7 @@ describe('the keywords of a split topic', () => {
return doc?.name;
};
const roots = [...docs.values()]
- .filter(doc => doc.type === 'namespace' && !parentOf(doc) && doc.name !== 'cli')
+ .filter(doc => doc.type === 'namespace' && !parentOf(doc) && !['cli', 'authoring'].includes(doc.name))
.map(doc => doc.name);
expect(roots).toContain('layout');
diff --git a/packages/cli/foundation/doc-compiler/tree.mjs b/packages/cli/foundation/doc-compiler/tree.mjs
index c70a3f6022..033fa379db 100644
--- a/packages/cli/foundation/doc-compiler/tree.mjs
+++ b/packages/cli/foundation/doc-compiler/tree.mjs
@@ -12,7 +12,7 @@
* @position Between discovery and the readers: `astryx docs <route>`,
* `astryx doctor`, and the docsite build all read this tree. The CLI's docs
* and each integration's have a home here, and a flat topic's home is the
- * generated Unorganized level.
+ * generated level for its category: Guides or Foundations.
* A namespace never scans files and never lists its children: a child names
* its parent, or a namespace adopts a discovery group.
*/
@@ -113,20 +113,49 @@ export const KIND_GROUPS = Object.freeze({
/**
* A flat topic: a reference topic that no namespace places. The tree gives it
- * a home in the generated Unorganized level, under its own name.
+ * a home in the generated level for its category (Guides or Foundations),
+ * under its own name.
* @typedef {object} TreeTopicInput
* @property {string} provider the package that owns the topic
* @property {string} providerId the provider's ProviderId
* @property {string} name the topic's name, which stays its route
* @property {string} title
* @property {string} summary
+ * @property {string | null} [category] the topic's sidebar group:
+ * `foundations` puts it in Foundations; anything else, in Guides
* @property {string} source where the topic comes from, for diagnostics
* @property {string[]} [aliases] every other name the topic answers to: the
* topics it replaced, directly or through a chain
*/
-/** The route of the generated level that holds every flat topic. */
-export const UNORGANIZED = 'unorganized';
+/**
+ * The generated levels that hold the flat topics, by category
+ * (spec:AST-046 FR12). A topic keeps its own name as its route; its level is
+ * only where it sits. Readers see these titles in a topic's path, so each is
+ * a plain name for what the topics are.
+ */
+export const TOPIC_LEVELS = Object.freeze({
+ guides: Object.freeze({
+ route: 'guides',
+ title: 'Guides',
+ summary:
+ 'Guides that stand on their own: getting started, principles, theming, and working with AI. Each topic keeps its own name; open one by it.',
+ }),
+ foundations: Object.freeze({
+ route: 'foundations',
+ title: 'Foundations',
+ summary:
+ 'Color, elevation, icons, illustrations, motion, shape, and spacing: the visual foundations every component builds on. Each topic keeps its own name; open one by it.',
+ }),
+});
+
+/**
+ * The generated level a flat topic sits in.
+ * @param {string | null | undefined} category
+ * @returns {'guides' | 'foundations'}
+ */
+export const topicLevel = category =>
+ category === 'foundations' ? 'foundations' : 'guides';
/**
* @typedef {object} TreeNode
@@ -145,7 +174,7 @@ export const UNORGANIZED = 'unorganized';
* @property {string | null} slot the parent slot this node sits in
* @property {number | null} order
* @property {boolean} generated made by the compiler (a `groupBy: 'kind'`
- * level, or the Unorganized level), not authored
+ * level, or a flat topics' level), not authored
* @property {TreeSlot[]} slots a namespace's slots; empty for a leaf
* @property {string} source
* @property {any} [ref]
@@ -216,7 +245,7 @@ function resolveParent(parent, provider, declared) {
* the one adoption rule in its package that matches its group and kind. A
* placement that fails withdraws the doc; it never falls back to adoption. A
* doc with neither is a flat topic: it keeps its flat name as its route, and its
- * home is the generated Unorganized level. The CLI keeps its own routes: an
+ * home is the generated level for its category. The CLI keeps its own routes: an
* integration's node that would take one is withdrawn with a diagnostic.
*
* @param {{namespaces: TreeNamespaceInput[], docs: TreeDocInput[], topics?: TreeTopicInput[]}} inputs
@@ -237,10 +266,15 @@ export function buildDocsTree({namespaces, docs, topics = []}) {
);
// Routes the CLI's own docs keep (spec:AST-046 FR11): the name of each of
- // its flat topics, and the generated Unorganized level. Its namespaces keep
- // theirs by rank, because they go into the tree first. Routes compare
- // without case, as topic names do, so `CLI` claims `cli`.
- const cliRoutes = new Set(topics.length > 0 ? [UNORGANIZED] : []);
+ // its flat topics, and the generated levels that hold flat topics. Its
+ // namespaces keep theirs by rank, because they go into the tree first.
+ // Routes compare without case, as topic names do, so `CLI` claims `cli`.
+ /** @type {Set<string>} */
+ const cliRoutes = new Set(
+ topics.length > 0
+ ? Object.values(TOPIC_LEVELS).map(level => level.route)
+ : [],
+ );
for (const topic of topics) {
if (topic.provider === CLI_PROVIDER)
cliRoutes.add(topic.name.toLowerCase());
@@ -592,20 +626,21 @@ export function buildDocsTree({namespaces, docs, topics = []}) {
);
}
- // The generated Unorganized level (spec:AST-046 FR12): every flat topic sits
- // here, in the order the topic list reads, so every doc has a home in the
- // tree. A topic keeps its own name as its route.
- if (topics.length > 0) {
+ // The generated levels (spec:AST-046 FR12): every flat topic sits in the
+ // level for its category, in the order the topic list reads, so every doc
+ // has a named home in the tree. A topic keeps its own name as its route.
+ for (const [key, level] of Object.entries(TOPIC_LEVELS)) {
+ const members = topics.filter(topic => topicLevel(topic.category) === key);
+ if (members.length === 0) continue;
const home = {
id: null,
- route: UNORGANIZED,
+ route: level.route,
kind: 'namespace',
provider: CLI_PROVIDER,
providerId: CLI_PROVIDER_ID,
- name: UNORGANIZED,
- title: 'Unorganized',
- summary:
- 'Every topic that no section places yet. Each keeps its own name; open one by it.',
+ name: level.route,
+ title: level.title,
+ summary: level.summary,
parent: null,
slot: null,
order: null,
@@ -613,30 +648,29 @@ export function buildDocsTree({namespaces, docs, topics = []}) {
slots: [{name: 'topics', title: 'Topics', children: []}],
source: 'generated',
};
- if (addNode(home, {provider: CLI_PROVIDER, source: 'generated'})) {
- topics.forEach((topic, i) => {
- addNode(
- {
- id: createDocId(topic.providerId, 'generic', topic.name),
- route: topic.name,
- kind: 'generic',
- provider: topic.provider,
- providerId: topic.providerId,
- name: topic.name,
- title: topic.title,
- summary: topic.summary,
- parent: UNORGANIZED,
- slot: 'topics',
- order: i,
- generated: false,
- slots: [],
- source: topic.source,
- ref: {flatTopic: topic.name},
- },
- topic,
- );
- });
- }
+ if (!addNode(home, {provider: CLI_PROVIDER, source: 'generated'})) continue;
+ members.forEach((topic, i) => {
+ addNode(
+ {
+ id: createDocId(topic.providerId, 'generic', topic.name),
+ route: topic.name,
+ kind: 'generic',
+ provider: topic.provider,
+ providerId: topic.providerId,
+ name: topic.name,
+ title: topic.title,
+ summary: topic.summary,
+ parent: level.route,
+ slot: 'topics',
+ order: i,
+ generated: false,
+ slots: [],
+ source: topic.source,
+ ref: {flatTopic: topic.name},
+ },
+ topic,
+ );
+ });
}
// Children, per slot, in reading order: order, then title, then id.
diff --git a/packages/cli/foundation/doc-compiler/tree.test.mjs b/packages/cli/foundation/doc-compiler/tree.test.mjs
index ff35b6d22b..7bb11b1353 100644
--- a/packages/cli/foundation/doc-compiler/tree.test.mjs
+++ b/packages/cli/foundation/doc-compiler/tree.test.mjs
@@ -154,21 +154,21 @@ describe('buildDocsTree', () => {
source: `${provider}/${name}.doc.mjs`,
});
const cliNs = {...ns('cli'), provider: CLI, providerId: CLI, source: `${CLI}/tree/cli.doc.mjs`};
- // An integration's topics named `CLI` and `UNORGANIZED` claim the CLI's
- // namespace and the generated level; both are withdrawn.
+ // An integration's topics named `CLI` and `GUIDES` claim the CLI's
+ // namespace and a generated level; both are withdrawn.
const tree = buildDocsTree({
namespaces: [cliNs],
docs: [],
- topics: [topic('theme', CLI), topic('CLI'), topic('UNORGANIZED')],
+ topics: [topic('theme', CLI), topic('CLI'), topic('GUIDES')],
});
expect(tree.get('cli')?.provider).toBe(CLI);
- expect(tree.get('unorganized')?.provider).toBe(CLI);
+ expect(tree.get('guides')?.provider).toBe(CLI);
expect(routes(tree)).not.toContain('CLI');
- expect(routes(tree)).not.toContain('UNORGANIZED');
+ expect(routes(tree)).not.toContain('GUIDES');
expect(problems(tree)).toEqual(
expect.arrayContaining([
['duplicate_route', expect.stringContaining('both have the route "CLI"')],
- ['duplicate_route', expect.stringContaining('takes the route "UNORGANIZED", which the CLI\'s own docs keep')],
+ ['duplicate_route', expect.stringContaining('takes the route "GUIDES", which the CLI\'s own docs keep')],
]),
);
// It names both docs as their authors know them, never by artifact id,
@@ -502,7 +502,7 @@ describe("the CLI's own docs tree", () => {
async () => {
const tree = await loadDocsTree({fresh: true});
expect(tree.diagnostics).toEqual([]);
- expect(tree.roots().map(node => node.route)).toEqual(['cli', 'global', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography']);
+ expect(tree.roots().map(node => node.route)).toEqual(['authoring', 'cli', 'global', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography']);
// Every slot child is a node one level below the namespace that places
// it, and every node but the root is placed. Read from the tree, so a
// restructure of the guides does not need this test edited.
diff --git a/packages/cli/test/__golden__/docs-index.txt b/packages/cli/test/__golden__/docs-index.txt
index 73ac4e25cc..db265a3b2e 100644
--- a/packages/cli/test/__golden__/docs-index.txt
+++ b/packages/cli/test/__golden__/docs-index.txt
@@ -8,5 +8,5 @@ colors Colors - Cards use the core tokens.
Read one section: pnpm exec astryx docs acme-guide <section>
Read everything: pnpm exec astryx docs acme-guide --full
-Up: pnpm exec astryx docs unorganized
+Up: pnpm exec astryx docs guides
Previous: pnpm exec astryx docs working-with-ai
diff --git a/packages/cli/test/__golden__/docs-list.json b/packages/cli/test/__golden__/docs-list.json
index 9ae4d37d4a..edbe5fe334 100644
--- a/packages/cli/test/__golden__/docs-list.json
+++ b/packages/cli/test/__golden__/docs-list.json
@@ -10,9 +10,19 @@
],
"meta": {
"namespaces": [
+ {
+ "topic": "authoring",
+ "description": "Build an npm package that adds components, templates, themes, docs, and codemods to Astryx apps, and look up every field of every file it holds.",
+ "package": "@astryxdesign/cli"
+ },
{
"topic": "cli",
- "description": "Commands, programmatic APIs, integration authoring, and output contracts.",
+ "description": "Commands, programmatic APIs, and output contracts. Building an integration is under `astryx docs authoring`.",
+ "package": "@astryxdesign/cli"
+ },
+ {
+ "topic": "foundations",
+ "description": "Color, elevation, icons, illustrations, motion, shape, and spacing: the visual foundations every component builds on. Each topic keeps its own name; open one by it.",
"package": "@astryxdesign/cli"
},
{
@@ -20,6 +30,11 @@
"description": "Install Astryx once on your computer and use it in any folder. Each project still runs its own version of Astryx, so a global install never changes what a project gets.",
"package": "@astryxdesign/cli"
},
+ {
+ "topic": "guides",
+ "description": "Guides that stand on their own: getting started, principles, theming, and working with AI. Each topic keeps its own name; open one by it.",
+ "package": "@astryxdesign/cli"
+ },
{
"topic": "internationalization",
"description": "Set the active locale, load catalogs, coexist with your own i18n library, handle RTL, and test translations.",
@@ -54,11 +69,6 @@
"topic": "typography",
"description": "Font families, geometric type scale, weight, line-height, and semantic text tokens for consistent, accessible text styling.",
"package": "@astryxdesign/cli"
- },
- {
- "topic": "unorganized",
- "description": "Every topic that no section places yet. Each keeps its own name; open one by it.",
- "package": "@astryxdesign/cli"
}
],
"answeredBy": {
diff --git a/packages/cli/test/__golden__/docs-topic-text.txt b/packages/cli/test/__golden__/docs-topic-text.txt
index 24e35e83ba..d3a79112dc 100644
--- a/packages/cli/test/__golden__/docs-topic-text.txt
+++ b/packages/cli/test/__golden__/docs-topic-text.txt
@@ -14,5 +14,5 @@ Cards use the core tokens.
[token-ref: unknown topic "no-such-topic"]
-Up: pnpm exec astryx docs unorganized
+Up: pnpm exec astryx docs guides
Previous: pnpm exec astryx docs working-with-ai
diff --git a/packages/cli/test/__golden__/docs-topic.json b/packages/cli/test/__golden__/docs-topic.json
index 0f72633440..5302d1c325 100644
--- a/packages/cli/test/__golden__/docs-topic.json
+++ b/packages/cli/test/__golden__/docs-topic.json
@@ -36,7 +36,7 @@
}
],
"links": {
- "up": "astryx docs unorganized",
+ "up": "astryx docs guides",
"previous": "astryx docs working-with-ai"
}
},
diff --git a/packages/cli/test/__golden__/search.json b/packages/cli/test/__golden__/search.json
index c74de74185..71aa3a1fba 100644
--- a/packages/cli/test/__golden__/search.json
+++ b/packages/cli/test/__golden__/search.json
@@ -22,9 +22,9 @@
"score": 50,
"reason": "description mentions \"zorblax\"",
"description": "How zorblax cards fit together.",
- "title": "Unorganized › Acme guide",
+ "title": "Guides › Acme guide",
"command": "astryx docs acme-guide --index",
- "parent": "astryx docs unorganized"
+ "parent": "astryx docs guides"
},
{
"domain": "template",
diff --git a/packages/cli/test/docs-graph.test.mjs b/packages/cli/test/docs-graph.test.mjs
index 0f0fe5c224..9ebcd929b1 100644
--- a/packages/cli/test/docs-graph.test.mjs
+++ b/packages/cli/test/docs-graph.test.mjs
@@ -319,7 +319,7 @@ const HINT_READS = [
['docs', 'cli'],
['docs', 'cli/api/functions/search'],
['docs', 'theme'],
- ['docs', 'cli/integrations', 'codemods'],
+ ['docs', 'authoring', 'codemods'],
['search', 'token-ref', '--type', 'doc'],
['--help'],
['docs', '--help'],
@@ -394,10 +394,14 @@ describe('the docs graph', () => {
/** @type {string[]} */
const unreached = [];
// Command, API, schema, enum, and authoring docs: a tree leaf, or a section
- // of `astryx docs authoring`.
+ // of the field reference, which `astryx docs authoring <name>` reads.
const {loaded, failed} = await loadCliSelfDocs(discoverCliSelfDocSources(CLI), CLI);
expect(failed).toEqual([]);
- const authoring = reads.get(`${TOP} authoring --index`)?.data.sections ?? [];
+ const authoring =
+ reads.get(`${TOP} authoring/field-reference --index`)?.data.sections ??
+ reads.get(`${TOP} authoring/field-reference`)?.data.sections ??
+ [];
+ expect(authoring.length).toBeGreaterThan(10);
for (const {source, doc} of loaded) {
const leaf = [...tree.nodes.values()].find(
node => node.kind === doc.type && node.name === doc.name,
@@ -408,7 +412,10 @@ describe('the docs graph', () => {
const ok = leaf
? reached(`${TOP} ${leaf.route}`)
: section
- ? reached(`${TOP} authoring ${section.id}`)
+ ? reached(`${TOP} authoring ${section.id}`) ||
+ reached(`${TOP} authoring/field-reference ${section.id}`) ||
+ // The walk opens the field reference whole, with every section.
+ reached(`${TOP} authoring/field-reference`)
: false;
if (!ok) unreached.push(source);
}
@@ -609,7 +616,7 @@ describe('the docs graph', () => {
it("opens every search hit's command and parent", async () => {
/** @type {string[]} */
const broken = [];
- for (const query of ['assertResponse', 'token-ref', 'codemod protected files', 'agent docs', 'ERR_UNKNOWN_SECTION', 'theme', 'unorganized', 'Astryx CLI']) {
+ for (const query of ['assertResponse', 'token-ref', 'codemod protected files', 'agent docs', 'ERR_UNKNOWN_SECTION', 'theme', 'foundations', 'Astryx CLI']) {
const {data} = await search(query, {type: 'doc', limit: 20});
for (const hit of data.results) {
if (!hit.parent) broken.push(`"${query}": ${hit.name} has no parent`);