@okfit/profiles 0.8.3 → 0.9.0

package/Publications.js

@@ -0,0 +1,133 @@
+import { Derivation } from "./Derivation.js";
+import { ConceptId, Diagnostic, DiagnosticRange, OkfitConfig } from "@okfit/core";
+import { Effect, Option } from "effect";
+
+//#region src/Publications.ts
+/**
+* The concept type name of a documentation surface.
+*
+* @public
+*/
+const SURFACE_TYPE = "Surface";
+/**
+* The concept type name of a published page rendered from bundle concepts.
+*
+* @public
+*/
+const PUBLICATION_TYPE = "Publication";
+const resolveRef = (from, raw) => {
+	const segments = from.split("/").slice(0, -1);
+	for (const part of raw.replace(/\.md$/u, "").split("/")) {
+		if (part === "" || part === ".") continue;
+		if (part === "..") {
+			if (segments.length === 0) return "";
+			segments.pop();
+			continue;
+		}
+		segments.push(part);
+	}
+	return segments.join("/");
+};
+const rendersOf = (concept) => {
+	const value = concept.frontmatter.raw.renders;
+	if (!Array.isArray(value)) return void 0;
+	const out = [];
+	for (const [index, entry] of value.entries()) {
+		if (typeof entry !== "object" || entry === null || typeof entry.path !== "string") return void 0;
+		const digest = typeof entry.body_sha256 === "string" && entry.body_sha256 !== "" ? entry.body_sha256 : void 0;
+		out.push(digest === void 0 ? {
+			index,
+			path: entry.path
+		} : {
+			index,
+			path: entry.path,
+			body_sha256: digest
+		});
+	}
+	return out;
+};
+const compare = (a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : a.code < b.code ? -1 : a.code > b.code ? 1 : 0;
+/**
+* A profiles-owned lint over Publication concepts: `publication-orphan` when a
+* `surface` or `renders[].path` does not resolve to a bundle concept (or
+* `renders` is malformed), and `publication-drift` when a rendered source's
+* body digest no longer matches the stamped `body_sha256`. Total over
+* severity: returns `[]` before any digest work when both codes are `"off"`.
+*
+* @public
+*/
+var Publications = class {
+	constructor() {}
+	/** Resolves a raw reference against a bundle-relative concept path; `""` when it escapes the bundle. */
+	static resolveRef = resolveRef;
+	/** The `renders` entries of a Publication, or `undefined` when malformed. */
+	static rendersOf = rendersOf;
+	/** Lints every Publication in `bundle`; diagnostics are sorted by file then code. */
+	static lint = Effect.fn("Publications.lint")(function* (bundle, config) {
+		const driftSeverity = OkfitConfig.severityFor(config, "publication-drift");
+		const orphanSeverity = OkfitConfig.severityFor(config, "publication-orphan");
+		if (driftSeverity === "off" && orphanSeverity === "off") return [];
+		const diagnostics = [];
+		const push = (concept, code, severity, message, path) => {
+			const range = DiagnosticRange.forFrontmatterPath(concept.document, path);
+			diagnostics.push(Diagnostic.make({
+				file: concept.path,
+				code,
+				severity,
+				message,
+				...range === void 0 ? {} : { range }
+			}));
+		};
+		for (const [id, concept] of bundle.concepts) {
+			if (concept.frontmatter.type !== "Publication") continue;
+			const resource = String(concept.frontmatter.raw.resource ?? concept.path);
+			if (orphanSeverity !== "off") {
+				const surface = concept.frontmatter.raw.surface;
+				if (surface !== void 0) {
+					const target = typeof surface === "string" ? Option.match(ConceptId.normalize(resolveRef(concept.path, surface)), {
+						onNone: () => void 0,
+						onSome: (key) => bundle.concepts.get(key)
+					}) : void 0;
+					if (target === void 0) push(concept, "publication-orphan", orphanSeverity, `surface ${JSON.stringify(surface)} does not resolve to a concept in the bundle`, ["surface"]);
+					else if (target.frontmatter.type !== "Surface") push(concept, "publication-orphan", orphanSeverity, `surface ${JSON.stringify(surface)} resolves to a concept of type ${JSON.stringify(target.frontmatter.type)}, not ${SURFACE_TYPE}`, ["surface"]);
+				}
+			}
+			const renders = rendersOf(concept);
+			if (renders === void 0) {
+				if (orphanSeverity !== "off") push(concept, "publication-orphan", orphanSeverity, "renders must be a list of { path, body_sha256 } entries", ["renders"]);
+				continue;
+			}
+			if (renders.length === 0) {
+				if (orphanSeverity !== "off") push(concept, "publication-orphan", orphanSeverity, "renders must name at least one source", ["renders"]);
+				continue;
+			}
+			const stale = [];
+			for (const entry of renders) {
+				const sourceId = resolveRef(concept.path, entry.path);
+				const source = Option.match(ConceptId.normalize(sourceId), {
+					onNone: () => void 0,
+					onSome: (key) => bundle.concepts.get(key)
+				});
+				if (source === void 0) {
+					if (orphanSeverity !== "off") push(concept, "publication-orphan", orphanSeverity, `renders[${entry.index}].path ${JSON.stringify(entry.path)} does not resolve to a concept in the bundle`, [
+						"renders",
+						entry.index,
+						"path"
+					]);
+					continue;
+				}
+				if (driftSeverity === "off") continue;
+				if (entry.body_sha256 === void 0) {
+					stale.push(`${sourceId} (never stamped)`);
+					continue;
+				}
+				if ((yield* Derivation.bodyDigest(source.document.source)) !== entry.body_sha256) stale.push(`${sourceId} (changed)`);
+			}
+			if (stale.length > 0 && driftSeverity !== "off") push(concept, "publication-drift", driftSeverity, `Rendered page ${resource} is stale against: ${stale.join(", ")}; re-render it, then run okfit sync --publication ${id}`, ["renders"]);
+		}
+		return diagnostics.sort(compare);
+	});
+};
+
+//#endregion
+export { PUBLICATION_TYPE, Publications, SURFACE_TYPE };

package/README.md

@@ -163,6 +163,54 @@ description = "The ISO 8601 date the failure happened or was first observed."
 description = "A path relative to this concept file to the test, check, or config that now stops the failure recurring."
 kind = "path"
 
+[types.Surface]
+description = "A documentation surface: where one kind of published docs lives, who reads it, and how it is written."
+guidance = "Write the body as instructions to the author of a page on this surface: tone, structure, required and forbidden sections, and what belongs on another surface instead. Keep one Surface per audience and location, and point links_to at the Surface this one routes readers to."
+required = ["kind", "audience", "resource"]
+
+[types.Surface.fields.kind]
+description = "How the surface is published."
+
+[types.Surface.fields.kind.values]
+site = "A built website workspace, such as an RSPress site, published at a URL."
+repo = "Markdown read in place on the forge, such as a docs/ directory on GitHub."
+readme = "README files: the repository root's, each package's, or both."
+
+[types.Surface.fields.audience]
+description = "Who the surface is written for."
+
+[types.Surface.fields.audience.values]
+users = "People installing or calling what this repository ships."
+contributors = "People changing this repository: setup, workflow, and internals."
+agents = "Coding agents working in this repository."
+
+[types.Surface.fields.resource]
+description = "A path relative to this concept file to the surface root, or a glob pattern when the surface spans many directories, such as every package directory."
+kind = "path"
+
+[types.Surface.fields.url]
+description = "Where a site surface is published, as an absolute URL."
+
+[types.Surface.fields.links_to]
+description = "The Surface this one routes readers to, such as a one-page README pointing at the site."
+kind = "path"
+
+[types.Publication]
+description = "A published page that restates facts this bundle owns, and the concepts it was rendered from."
+guidance = "Create one only for a page whose content comes from bundle concepts; the bundle is the source of truth and the page is re-rendered when a source changes. Use the body for rendering notes: what is audience-specific, what is deliberately left out, and what a re-render must keep."
+required = ["resource", "surface", "renders"]
+
+[types.Publication.fields.resource]
+description = "A path relative to this concept file to the published page."
+kind = "path"
+
+[types.Publication.fields.surface]
+description = "The Surface concept this page is published on."
+kind = "path"
+
+[types.Publication.fields.renders]
+description = "The source concepts as a list of entries that each hold a path and a body digest; okfit sync --publication stamps each digest."
+
 [tags.architecture]
 description = "Concerns the shape of the system rather than one module."
 

package/SoftwareProject.js

@@ -1,3 +1,4 @@
+import { DOCS_PRESETS } from "./presets/index.js";
 import { DiagnosticRange } from "@okfit/core";
 
 //#region src/SoftwareProject.ts
@@ -170,6 +171,62 @@ const config = {
 					kind: "path"
 				}
 			}
+		},
+		Surface: {
+			description: "A documentation surface: where one kind of published docs lives, who reads it, and how it is written.",
+			guidance: "Write the body as instructions to the author of a page on this surface: tone, structure, required and forbidden sections, and what belongs on another surface instead. Keep one Surface per audience and location, and point links_to at the Surface this one routes readers to.",
+			required: [
+				"kind",
+				"audience",
+				"resource"
+			],
+			fields: {
+				kind: {
+					description: "How the surface is published.",
+					values: {
+						site: "A built website workspace, such as an RSPress site, published at a URL.",
+						repo: "Markdown read in place on the forge, such as a docs/ directory on GitHub.",
+						readme: "README files: the repository root's, each package's, or both."
+					}
+				},
+				audience: {
+					description: "Who the surface is written for.",
+					values: {
+						users: "People installing or calling what this repository ships.",
+						contributors: "People changing this repository: setup, workflow, and internals.",
+						agents: "Coding agents working in this repository."
+					}
+				},
+				resource: {
+					description: "A path relative to this concept file to the surface root, or a glob pattern when the surface spans many directories, such as every package directory.",
+					kind: "path"
+				},
+				url: { description: "Where a site surface is published, as an absolute URL." },
+				links_to: {
+					description: "The Surface this one routes readers to, such as a one-page README pointing at the site.",
+					kind: "path"
+				}
+			}
+		},
+		Publication: {
+			description: "A published page that restates facts this bundle owns, and the concepts it was rendered from.",
+			guidance: "Create one only for a page whose content comes from bundle concepts; the bundle is the source of truth and the page is re-rendered when a source changes. Use the body for rendering notes: what is audience-specific, what is deliberately left out, and what a re-render must keep.",
+			required: [
+				"resource",
+				"surface",
+				"renders"
+			],
+			fields: {
+				resource: {
+					description: "A path relative to this concept file to the published page.",
+					kind: "path"
+				},
+				surface: {
+					description: "The Surface concept this page is published on.",
+					kind: "path"
+				},
+				renders: { description: "The source concepts as a list of entries that each hold a path and a body digest; okfit sync --publication stamps each digest." }
+			}
 		}
 	},
 	tags: {
@@ -256,6 +313,14 @@ const layout = {
 		{
 			directory: "incidents",
 			type: "Incident"
+		},
+		{
+			directory: "surfaces",
+			type: "Surface"
+		},
+		{
+			directory: "publications",
+			type: "Publication"
 		}
 	]
 };
@@ -306,6 +371,7 @@ const softwareProject = {
 	name: "software-project",
 	config,
 	layout,
+	docsPresets: DOCS_PRESETS,
 	check
 };
 

package/index.d.ts

@@ -1,6 +1,6 @@
 import { Context, Crypto, DateTime, Effect, FileSystem, Layer, Option, Path, PlatformError, Schema } from "effect";
 import { Git, GitCommandError, NotARepositoryError, UnknownRefError } from "@effected/git";
-import { Actor, Diagnostic, DiagnosticRange, LoadedBundle, OkfitConfig } from "@okfit/core";
+import { Actor, Diagnostic, DiagnosticRange, LoadedBundle, LoadedConcept, OkfitConfig } from "@okfit/core";
 import { ChildProcessSpawner } from "effect/process";
 //#region src/BodyProvenance.d.ts
 /**
@@ -354,6 +354,41 @@ export declare const ProfileDiagnostic: Schema.Struct<{
  * @public
  */
 export type ProfileDiagnostic = typeof ProfileDiagnostic.Type;
+/**
+ * One Surface concept a docs preset writes: a bundle-relative `file` and the
+ * frontmatter and body to write there. `resource` is relative to the file.
+ * The `site` preset's `url` is an `https://example.invalid` placeholder the
+ * docs skill replaces.
+ *
+ * @public
+ */
+interface SurfaceTemplate {
+  readonly file: string;
+  readonly frontmatter: {
+    readonly type: "Surface";
+    readonly status: "draft";
+    readonly title: string;
+    readonly description: string;
+    readonly kind: "site" | "repo" | "readme";
+    readonly audience: "users" | "contributors" | "agents";
+    readonly resource: string;
+    readonly links_to?: string;
+    readonly url?: string;
+  };
+  readonly body: string;
+}
+/**
+ * A named set of Surface templates for one repository shape. `additive` is
+ * true only for `site`, which layers on another preset instead of replacing it.
+ *
+ * @public
+ */
+interface DocsPreset {
+  readonly name: "npm-package" | "monorepo-router" | "monorepo-shared-docs" | "site";
+  readonly description: string;
+  readonly additive: boolean;
+  readonly surfaces: ReadonlyArray<SurfaceTemplate>;
+}
 /**
  * A named profile (P-38): a partial `OkfitConfig` the CLI merges as
  * `DEFAULTS < profile < file`, a scaffolding `Layout`, and a pure `check`
@@ -365,6 +400,7 @@ interface Profile {
   readonly name: ProfileName;
   readonly config: OkfitConfig;
   readonly layout: Layout;
+  readonly docsPresets: ReadonlyArray<DocsPreset>;
   readonly check: (bundle: LoadedBundle) => ReadonlyArray<ProfileDiagnostic>;
 }
 //#endregion
@@ -442,5 +478,47 @@ export declare class Provenance {
   }) => Effect.Effect<ReadonlyArray<Diagnostic>, GitHistoryError | GitCommandError | UnknownRefError | PlatformError.PlatformError, Git | GitHistory | FileSystem.FileSystem | Path.Path | Crypto.Crypto>;
 }
 //#endregion
-export type { GeneratedAtError, GeneratedAtOptions, GeneratedByError, GeneratedByOptions, GitHistoryShape, GitIdentity, Layout, LayoutDirectory, PathLogOptions, Profile, ProfileName, UncommittedReason, Writer };
+//#region src/Publications.d.ts
+/**
+ * The concept type name of a documentation surface.
+ *
+ * @public
+ */
+export declare const SURFACE_TYPE: "Surface";
+/**
+ * The concept type name of a published page rendered from bundle concepts.
+ *
+ * @public
+ */
+export declare const PUBLICATION_TYPE: "Publication";
+/**
+ * One entry of a Publication's `renders` list, with its position.
+ *
+ * @public
+ */
+interface RendersEntry {
+  readonly index: number;
+  readonly path: string;
+  readonly body_sha256?: string;
+}
+/**
+ * A profiles-owned lint over Publication concepts: `publication-orphan` when a
+ * `surface` or `renders[].path` does not resolve to a bundle concept (or
+ * `renders` is malformed), and `publication-drift` when a rendered source's
+ * body digest no longer matches the stamped `body_sha256`. Total over
+ * severity: returns `[]` before any digest work when both codes are `"off"`.
+ *
+ * @public
+ */
+export declare class Publications {
+  private constructor();
+  /** Resolves a raw reference against a bundle-relative concept path; `""` when it escapes the bundle. */
+  static readonly resolveRef: (from: string, raw: string) => string;
+  /** The `renders` entries of a Publication, or `undefined` when malformed. */
+  static readonly rendersOf: (concept: LoadedConcept) => ReadonlyArray<RendersEntry> | undefined;
+  /** Lints every Publication in `bundle`; diagnostics are sorted by file then code. */
+  static readonly lint: (bundle: LoadedBundle, config: OkfitConfig) => Effect.Effect<ReadonlyArray<Diagnostic>, PlatformError.PlatformError, Crypto.Crypto>;
+}
+//#endregion
+export type { DocsPreset, GeneratedAtError, GeneratedAtOptions, GeneratedByError, GeneratedByOptions, GitHistoryShape, GitIdentity, Layout, LayoutDirectory, PathLogOptions, Profile, ProfileName, RendersEntry, SurfaceTemplate, UncommittedReason, Writer };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -4,5 +4,6 @@ import { AgentActorUnconfiguredError, Derivation, HumanActorUnresolvedError } fr
 import { PROFILE_NAMES, ProfileDiagnostic, ProfileDiagnosticCode } from "./Profile.js";
 import { Profiles } from "./Profiles.js";
 import { Provenance } from "./Provenance.js";
+import { PUBLICATION_TYPE, Publications, SURFACE_TYPE } from "./Publications.js";
 
-export { AgentActorUnconfiguredError, BodyCommitted, BodyProvenance, BodyUncommitted, Derivation, GitHistory, GitHistoryError, HumanActorUnresolvedError, PROFILE_NAMES, PathHistoryEntry, ProfileDiagnostic, ProfileDiagnosticCode, Profiles, Provenance };
+export { AgentActorUnconfiguredError, BodyCommitted, BodyProvenance, BodyUncommitted, Derivation, GitHistory, GitHistoryError, HumanActorUnresolvedError, PROFILE_NAMES, PUBLICATION_TYPE, PathHistoryEntry, ProfileDiagnostic, ProfileDiagnosticCode, Profiles, Provenance, Publications, SURFACE_TYPE };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/profiles",
-	"version": "0.8.3",
+	"version": "0.9.0",
 	"private": false,
 	"description": "Named OKF configuration profiles for okfit, starting with the software-project profile.",
 	"keywords": [
@@ -37,7 +37,7 @@
 	"peerDependencies": {
 		"@effected/git": "^0.20.0",
 		"@effected/markdown": "^0.15.0",
-		"@okfit/core": "^0.8.4",
+		"@okfit/core": "^0.9.0",
 		"effect": "^4.0.0"
 	},
 	"engines": {

package/presets/index.js

@@ -0,0 +1,51 @@
+import { CONTRIBUTOR_GUIDES, DOCS_PACKAGE, DOCS_PACKAGES, DOCS_REPO, README_PACKAGE, README_PACKAGES, README_PACKAGES_ONE_PAGE, README_PACKAGE_ONE_PAGE, README_ROOT, README_ROOT_ONE_PAGE, SITE } from "./surfaces.js";
+
+//#region src/presets/index.ts
+/**
+* The docs-surface presets the `software-project` profile offers, one per
+* repository shape. Three replace a repository's surfaces; `site` is
+* additive and swaps the README templates for one-page variants that link to
+* the site.
+*
+* @public
+*/
+const DOCS_PRESETS = [
+	{
+		name: "npm-package",
+		description: "A single package published to npm: a README surface that links to a docs/ folder surface.",
+		additive: false,
+		surfaces: [README_PACKAGE, DOCS_PACKAGE]
+	},
+	{
+		name: "monorepo-router",
+		description: "A monorepo whose root README routes to per-package READMEs.",
+		additive: false,
+		surfaces: [README_ROOT, README_PACKAGES]
+	},
+	{
+		name: "monorepo-shared-docs",
+		description: "A monorepo with routing READMEs plus a shared root docs/ folder, contributor guides and per-package docs/ folders read on the forge.",
+		additive: false,
+		surfaces: [
+			README_ROOT,
+			README_PACKAGES,
+			DOCS_REPO,
+			DOCS_PACKAGES,
+			CONTRIBUTOR_GUIDES
+		]
+	},
+	{
+		name: "site",
+		description: "A documentation website plus one-page README variants that link to it; keep the variants that match the repository shape.",
+		additive: true,
+		surfaces: [
+			SITE,
+			README_ROOT_ONE_PAGE,
+			README_PACKAGES_ONE_PAGE,
+			README_PACKAGE_ONE_PAGE
+		]
+	}
+];
+
+//#endregion
+export { DOCS_PRESETS };

package/presets/surfaces.js

@@ -0,0 +1,318 @@
+//#region src/presets/surfaces.ts
+const FENCE = "```";
+/**
+* The durable prose rules every surface body repeats, ported from the
+* design-docs `user-docs` agent. Kept as one list so the rules cannot drift
+* between surfaces.
+*/
+const RULES = [
+	"## Prose rules",
+	"",
+	"- Use sentence case for every heading: `## API reference`, not `## API Reference`. Acronyms and proper nouns keep their case.",
+	"- Put every paragraph and list item on one source line; never hard-wrap prose.",
+	"- Give every code fence a language identifier.",
+	"- Show the expected output of every example that logs a value or runs a command, as comments on the lines after it: `// ...` for JavaScript and TypeScript, `# ...` for shell.",
+	"- Never invent output, paths, identifiers or messages; when the real output cannot be verified from the source or by running the command, write a generic placeholder such as `# example output (varies by environment)`.",
+	"- Lead install commands with npm or npx and list at most one alternative (pnpm, yarn or bun) below it, unless the page is about package-manager-specific behavior.",
+	"- Never write a specific version number in prose; the npm badge and `package.json` are the source of truth. Do not state versions except in a migration guide between major versions.",
+	"- Match the language of the surrounding source and docs, and avoid filler, hype and AI-sounding phrasing.",
+	"- Never invent a tagline, feature or example: take them from `package.json`, the exported symbols and existing docs, and ask when none exist."
+].join("\n");
+const SINGLE_PACKAGE_SKELETON = [
+	`${FENCE}markdown`,
+	"# <package-name>",
+	"",
+	"<badges, built with the docs badge tooling rather than typed by hand>",
+	"",
+	"<one-paragraph tagline: what this is, what it does, why someone wants it>",
+	"",
+	"## Install",
+	"",
+	"<npm command and at most one alternative line>",
+	"",
+	"Requires <runtime> <engine range>.",
+	"",
+	"## Quick start",
+	"",
+	"<minimal worked example in one code block, with expected output as comments>",
+	"",
+	"## Features",
+	"",
+	"<bulleted list, one sentence each>",
+	"",
+	"## Documentation",
+	"",
+	"<one bullet per topical page in docs/; omit the section when docs/ has none>",
+	"",
+	"## License",
+	"",
+	"[<license>](LICENSE)",
+	FENCE
+].join("\n");
+const MONOREPO_ROOT_SKELETON = [
+	`${FENCE}markdown`,
+	"# <repo-name>",
+	"",
+	"<one paragraph: what the repository is and where it sits in its ecosystem>",
+	"",
+	"## Packages",
+	"",
+	"<table with Package and Purpose columns, each package linked to its directory>",
+	"",
+	"## Install",
+	"",
+	"<the common install command, or a pointer to each package README>",
+	"",
+	"## Requirements",
+	"",
+	"- <runtime> <engine range>",
+	"",
+	"## License",
+	"",
+	"[<license>](LICENSE)",
+	FENCE
+].join("\n");
+const DOCS_TOC_SKELETON = [
+	`${FENCE}markdown`,
+	"# <package-name> documentation",
+	"",
+	"<one-paragraph recap of the package, taken from the README tagline>",
+	"",
+	"## Install",
+	"",
+	"<the same npm install block as the README, optionally trimmed>",
+	"",
+	"## Pages",
+	"",
+	"<one bullet per page: a link and a one-line description>",
+	FENCE
+].join("\n");
+const ONE_PAGE_PACKAGE_SKELETON = [
+	`${FENCE}markdown`,
+	"# <package-name>",
+	"",
+	"<badges, built with the docs badge tooling rather than typed by hand>",
+	"",
+	"<one-paragraph tagline>",
+	"",
+	"## Install",
+	"",
+	"<npm command and at most one alternative line>",
+	"",
+	"## Quick start",
+	"",
+	"<one minimal example with expected output as comments>",
+	"",
+	"**Full documentation: <link to the site>**",
+	FENCE
+].join("\n");
+const ONE_PAGE_ROOT_SKELETON = [
+	`${FENCE}markdown`,
+	"# <repo-name>",
+	"",
+	"<one-paragraph summary of the repository>",
+	"",
+	"**Full documentation: <link to the site>**",
+	"",
+	"## Packages",
+	"",
+	"<table with Package and Purpose columns, each package linked to its directory>",
+	FENCE
+].join("\n");
+const CONTRIBUTOR_GUIDE_SKELETON = [
+	`${FENCE}markdown`,
+	"# <task, as a verb phrase: Make a pull request>",
+	"",
+	"<one sentence: what this guide gets the reader to>",
+	"",
+	"## Who this is for",
+	"",
+	"<the reader, e.g. a first-time contributor with a fork, and what they should already know>",
+	"",
+	"## Before you start",
+	"",
+	"<prerequisites as a list: tools and versions, access, a clean checkout, an issue to work from>",
+	"",
+	"## Steps",
+	"",
+	"1. <imperative step, with the exact command in a code fence>",
+	"2. <next step>",
+	"",
+	"## What success looks like",
+	"",
+	"<the observable end state: the passing check, the open PR, the command output>",
+	"",
+	"## Rules this guide follows",
+	"",
+	"<one bullet per rule the steps restate, each linking to the page that owns it>",
+	FENCE
+].join("\n");
+const body = (...parts) => parts.join("\n\n");
+/** The package README: published to npm, the package's onboarding page. */
+const README_PACKAGE = {
+	file: "surfaces/readme-package.md",
+	frontmatter: {
+		type: "Surface",
+		status: "draft",
+		title: "Package README",
+		description: "The README published to npm for a package, written for people who install it.",
+		kind: "readme",
+		audience: "users",
+		resource: "../../README.md",
+		links_to: "docs-repo.md"
+	},
+	body: body("# Package README", "## Who reads this", "People deciding whether to install the package and getting their first call working. They arrive from npm or the repository page with no context.", "## Required structure", "Follow this outline and fill it from the codebase: the tagline from `package.json` `description`, the features from the exported symbols, and the quick start from the simplest real call. Omit any section you cannot ground.", SINGLE_PACKAGE_SKELETON, "If `package.json` has no `engines` field, omit the runtime badge and the requirements line rather than guessing a range.", "## Other surfaces", "Contributor setup, internals and architecture belong in contributor docs; deep topical guides belong in `docs/`, listed under the Documentation section.", RULES)
+};
+/** The one-page package README that routes readers to the documentation site. */
+const README_PACKAGE_ONE_PAGE = {
+	file: "surfaces/readme-package.md",
+	frontmatter: {
+		type: "Surface",
+		status: "draft",
+		title: "Package README",
+		description: "A one-page README published to npm that routes readers to the documentation site.",
+		kind: "readme",
+		audience: "users",
+		resource: "../../README.md",
+		links_to: "site.md"
+	},
+	body: body("# Package README", "## Who reads this", "People deciding whether to install the package. The documentation site carries the full guides, so this page stays short.", "## Required structure", "Write exactly this and nothing more: the title, the badges, a tagline, the install command, one quick start, and a prominent link to the documentation site.", ONE_PAGE_PACKAGE_SKELETON, "Leave out Features, Documentation and every other section; the site carries them.", "## Other surfaces", "Anything longer than a quick start belongs on the documentation site this surface links to.", RULES)
+};
+/** The monorepo root README: a developer-facing hub, no badges. */
+const README_ROOT = {
+	file: "surfaces/readme-root.md",
+	frontmatter: {
+		type: "Surface",
+		status: "draft",
+		title: "Repository README",
+		description: "The monorepo root README: a hub that explains the packages and how they relate.",
+		kind: "readme",
+		audience: "contributors",
+		resource: "../../README.md"
+	},
+	body: body("# Repository README", "## Who reads this", "Contributors and visitors who landed on the repository and need to find the package they want. This page routes; it does not document any one package.", "## Required structure", "Follow this outline. Carry no badges on this page; they belong on each package README.", MONOREPO_ROOT_SKELETON, "Add an Ecosystem section only when the repository spans related but separate packages.", "## Other surfaces", "Per-package install and usage belong in each package README; contributor workflow belongs in contributor docs.", RULES)
+};
+/** The monorepo root README that routes readers to the documentation site. */
+const README_ROOT_ONE_PAGE = {
+	file: "surfaces/readme-root.md",
+	frontmatter: {
+		type: "Surface",
+		status: "draft",
+		title: "Repository README",
+		description: "A one-page monorepo root README that routes readers to the documentation site.",
+		kind: "readme",
+		audience: "contributors",
+		resource: "../../README.md",
+		links_to: "site.md"
+	},
+	body: body("# Repository README", "## Who reads this", "People who landed on the repository and need to find the package or guide they want.", "## Required structure", "Write exactly this and nothing more: the title, a one-paragraph summary, a prominent link to the documentation site, and the packages table. Carry no badges.", ONE_PAGE_ROOT_SKELETON, "## Other surfaces", "Guides and reference belong on the documentation site this surface links to.", RULES)
+};
+/** The README inside each monorepo package. */
+const README_PACKAGES = {
+	file: "surfaces/readme-packages.md",
+	frontmatter: {
+		type: "Surface",
+		status: "draft",
+		title: "Sub-package READMEs",
+		description: "The README inside each monorepo package, published to npm with the package.",
+		kind: "readme",
+		audience: "users",
+		resource: "../../packages/*/README.md"
+	},
+	body: body("# Sub-package READMEs", "## Who reads this", "People installing one package from npm. They never see the monorepo root README, so each page stands alone.", "## Required structure", "Use the single-package outline, with the badges built from that package's own `package.json`.", SINGLE_PACKAGE_SKELETON, "## Other surfaces", "How the packages relate belongs on the repository README; contributor workflow belongs in contributor docs.", RULES)
+};
+/** The one-page sub-package README that routes readers to the documentation site. */
+const README_PACKAGES_ONE_PAGE = {
+	file: "surfaces/readme-packages.md",
+	frontmatter: {
+		type: "Surface",
+		status: "draft",
+		title: "Sub-package READMEs",
+		description: "A one-page README inside each monorepo package that routes readers to the documentation site.",
+		kind: "readme",
+		audience: "users",
+		resource: "../../packages/*/README.md",
+		links_to: "site.md"
+	},
+	body: body("# Sub-package READMEs", "## Who reads this", "People installing one package from npm. The documentation site carries the full guides, so each page stays short.", "## Required structure", "Write exactly this and nothing more: the title, the badges, a tagline, the install command, one quick start, and a prominent link to the package's page on the documentation site.", ONE_PAGE_PACKAGE_SKELETON, "## Other surfaces", "Anything longer than a quick start belongs on the documentation site this surface links to.", RULES)
+};
+const docsRepo = (options) => ({
+	file: options.file,
+	frontmatter: {
+		type: "Surface",
+		status: "draft",
+		title: options.title,
+		description: options.description,
+		kind: "repo",
+		audience: options.audience,
+		resource: options.resource,
+		...options.linksTo === void 0 ? {} : { links_to: options.linksTo }
+	},
+	body: body(`# ${options.title1}`, "## Who reads this", options.reader, "## Required structure", "Name every page `{NN}-{slug}.md`: a two-digit zero-padded number and a kebab-case slug, such as `01-getting-started.md`. Start from `01-getting-started.md`, `02-api-reference.md` and `03-troubleshooting.md`; later topical pages slot between the first and the last two. Keep `README.md` as the table of contents:", DOCS_TOC_SKELETON, "List the pages with the docs table-of-contents tooling rather than by hand, and rename any page that breaks the filename format with `git mv`.", "## Other surfaces", "The one-page pitch and install command belong in the README; contributor workflow belongs in contributor docs.", RULES)
+});
+const USERS_DOCS_READER = "People who finished the README and want a guide, the API reference or troubleshooting help. They read the files on the forge, so every page must read well as plain markdown.";
+/** A `docs/` folder of topical pages for a single package, read on the forge. */
+const DOCS_PACKAGE = docsRepo({
+	file: "surfaces/docs-repo.md",
+	title: "Repository docs folder",
+	title1: "Repository docs folder",
+	description: "Topical markdown pages in docs/, read in place on the forge and linked from the README.",
+	audience: "users",
+	resource: "../../docs",
+	reader: USERS_DOCS_READER
+});
+/** The root `docs/` folder of a monorepo: shared contributor pages read on the forge. */
+const DOCS_REPO = docsRepo({
+	file: "surfaces/docs-repo.md",
+	title: "Repository docs folder",
+	title1: "Repository docs folder",
+	description: "Shared contributor pages in the root docs/, read in place on the forge and linked from the root README.",
+	audience: "contributors",
+	resource: "../../docs",
+	linksTo: "readme-root.md",
+	reader: "Contributors who need the shared workflow, architecture notes or release process. They read the files on the forge, so every page must read well as plain markdown."
+});
+/** The `docs/` folder inside each monorepo package. */
+const DOCS_PACKAGES = docsRepo({
+	file: "surfaces/docs-packages.md",
+	title: "Sub-package docs folders",
+	title1: "Sub-package docs folders",
+	description: "Topical markdown pages in each package's docs/, read in place on the forge and linked from its README.",
+	audience: "users",
+	resource: "../../packages/*/docs",
+	linksTo: "readme-packages.md",
+	reader: USERS_DOCS_READER
+});
+/** Step-by-step contributor guides in the root `docs/`, read on the forge. */
+const CONTRIBUTOR_GUIDES = {
+	file: "surfaces/contributor-guides.md",
+	frontmatter: {
+		type: "Surface",
+		status: "draft",
+		title: "Contributor guides",
+		description: "Task-shaped contributor guides in the root docs/, such as making a pull request, read in place on the forge.",
+		kind: "repo",
+		audience: "contributors",
+		resource: "../../docs",
+		links_to: "readme-root.md"
+	},
+	body: body("# Contributor guides", "## Who reads this", "Contributors about to do one concrete thing in the repository, such as open a pull request or cut a release. They follow the page top to bottom with a terminal open, so each guide is a procedure, not an essay.", "## Required structure", "Write one guide per task, named `{NN}-{slug}.md` like every other page in `docs/`, for example `01-making-a-pull-request.md`. Use this outline and omit no section:", CONTRIBUTOR_GUIDE_SKELETON, "State each rule the steps rely on once, in its own bullet under the last section, and link to the page that owns it rather than restating the rationale. Take commands from the repository's scripts and verify them before writing them down.", "## Other surfaces", "Reference material and architecture notes belong in the shared docs folder surface; the root README only routes to these guides.", RULES)
+};
+/** The documentation website. */
+const SITE = {
+	file: "surfaces/site.md",
+	frontmatter: {
+		type: "Surface",
+		status: "draft",
+		title: "Documentation site",
+		description: "The published documentation website: guides, reference and tutorials for people using the project.",
+		kind: "site",
+		audience: "users",
+		resource: "../../website",
+		url: "https://example.invalid"
+	},
+	body: body("# Documentation site", "## Who reads this", "People using the project who want guides, reference and worked tutorials. This is the long-form home; the READMEs only point here.", "## Required structure", "Organize pages by what the reader is trying to do: a getting-started path first, task guides next, reference last. Give every page one clear job, a sentence-case title and a short summary before the first heading. Link between pages instead of repeating their content.", "Replace the placeholder `url` in this concept's frontmatter with the real published address before relying on it.", "## Other surfaces", "The README carries only the pitch, the install command and one quick start, and links here for everything else; contributor workflow belongs in contributor docs.", RULES)
+};
+
+//#endregion
+export { CONTRIBUTOR_GUIDES, DOCS_PACKAGE, DOCS_PACKAGES, DOCS_REPO, README_PACKAGE, README_PACKAGES, README_PACKAGES_ONE_PAGE, README_PACKAGE_ONE_PAGE, README_ROOT, README_ROOT_ONE_PAGE, SITE };