@okfit/profiles 0.8.3 → 0.10.0

package/Canonical.js

@@ -0,0 +1,68 @@
+import { body } from "./internal/body.js";
+
+//#region src/Canonical.ts
+/** Top-level keys that are bookkeeping, not authored content (spec section 4). */
+const EXCLUDED_KEYS = /* @__PURE__ */ new Set([
+	"generated",
+	"verified",
+	"integrity",
+	"stale_after",
+	"status",
+	"timestamp"
+]);
+/** `JSON.stringify` omits these in an object and writes `null` for them in an array. */
+const isSkipped = (value) => value === void 0 || typeof value === "function" || typeof value === "symbol";
+/**
+* Canonical JSON: object keys sorted (`Array.prototype.toSorted`, UTF-16 code units)
+* at every depth; arrays keep their order. Byte-for-byte `JSON.stringify` of the
+* sorted value for every JSON-representable input, plus one extension: a `bigint`
+* (what the YAML decoder yields for an integer beyond 2^53, e.g. `ticket:
+* 123456789012345678901`) is written as its bare decimal literal. A literal cannot
+* collide with a string (strings are quoted) and is deterministic, where
+* `JSON.stringify` throws `TypeError` and would defect every caller that hashes.
+*/
+const json = (value) => {
+	if (typeof value === "bigint") return value.toString();
+	if (Array.isArray(value)) return `[${value.map((item) => isSkipped(item) ? "null" : json(item)).join(",")}]`;
+	if (value !== null && typeof value === "object") {
+		const record = value;
+		if (typeof record.toJSON === "function") return json(record.toJSON());
+		return `{${Object.keys(record).toSorted().filter((key) => !isSkipped(record[key])).map((key) => `${JSON.stringify(key)}:${json(record[key])}`).join(",")}}`;
+	}
+	return JSON.stringify(value);
+};
+const stripRendersDigests = (renders) => Array.isArray(renders) ? renders.map((entry) => {
+	if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return entry;
+	const { body: _body, body_sha256: _legacy, ...rest } = entry;
+	return rest;
+}) : renders;
+/**
+* The exact string a content digest hashes: canonical JSON of the authored frontmatter
+* (`raw` minus `Canonical.EXCLUDED_KEYS` and every `renders[].body`) and the
+* normalised body. `raw` is the parsed mapping (YAML 1.2 Core Schema: timestamps are
+* strings), so quoting, flow vs block style, key order and CRLF never change it.
+*/
+const contentInput = (raw, source) => {
+	const frontmatter = Object.fromEntries(Object.entries(raw).filter(([key]) => !EXCLUDED_KEYS.has(key)).map(([key, value]) => [key, key === "renders" ? stripRendersDigests(value) : value]));
+	return json({
+		body: body(source),
+		frontmatter
+	});
+};
+/**
+* Canonical encoding for okfit's content digest.
+*
+* @public
+*/
+var Canonical = class {
+	constructor() {}
+	/** Top-level frontmatter keys excluded from the content digest. */
+	static EXCLUDED_KEYS = EXCLUDED_KEYS;
+	/** Canonical JSON: sorted keys at every depth, array order kept; a `bigint` is its bare decimal literal. */
+	static json = json;
+	/** The exact string a content digest hashes. */
+	static contentInput = contentInput;
+};
+
+//#endregion
+export { Canonical };

package/Derivation.js

@@ -1,8 +1,9 @@
+import { body } from "./internal/body.js";
+import { Canonical } from "./Canonical.js";
 import { GitHistory } from "./GitHistory.js";
 import { Actor, OkfitConfig } from "@okfit/core";
 import { Crypto, DateTime, Duration, Effect, FileSystem, Option, Path, Schema } from "effect";
 import { Git } from "@effected/git";
-import { FrontmatterSource } from "@effected/markdown";
 import * as Hex from "effect/encoding/Hex";
 
 //#region src/Derivation.ts
@@ -35,15 +36,40 @@ var AgentActorUnconfiguredError = class extends Schema.TaggedError()("AgentActor
 		return "writer is agent but actors.agent is not configured";
 	}
 };
+/**
+* `git config okfit.actor` is set but is not a `human:<id>` actor without `@`
+* or glob characters. The value stays on the person's machine; okfit never
+* writes it anywhere.
+*
+* @public
+*/
+var ActorConfigInvalidError = class extends Schema.TaggedError()("ActorConfigInvalidError", { value: Schema.String }) {
+	get message() {
+		return `git config okfit.actor is "${this.value}"; it must be a human:<id> actor with no "@" and no * or ? (for example human:ada)`;
+	}
+};
+/**
+* The resolved human is not on a non-empty `[actors].humans` allow-list, so it
+* may not verify or revoke (spec section 8).
+*
+* @public
+*/
+var HumanActorNotAllowedError = class extends Schema.TaggedError()("HumanActorNotAllowedError", { actor: Schema.String }) {
+	get message() {
+		return `${this.actor} is not in [actors].humans, so it cannot verify or revoke; set your id with git config --global okfit.actor human:<id> to a listed id, or add ${this.actor} to [actors].humans`;
+	}
+};
 const HUMAN_PREFIX = "human:";
 const FALLBACK_STALE_AFTER = Duration.days(90);
 const decodeActor = Schema.decodeSync(Actor);
-const normalise = (text) => text.replace(/\r\n?/g, "\n").trimEnd();
-const body = (text) => normalise(FrontmatterSource.split(text).body);
-const bodyDigest = (text) => Effect.gen(function* () {
-	const bytes = yield* (yield* Crypto.Crypto).digest("SHA-256", new TextEncoder().encode(body(text)));
+const digestFull = (text) => Effect.gen(function* () {
+	const bytes = yield* (yield* Crypto.Crypto).digest("SHA-256", new TextEncoder().encode(text));
 	return Hex.encode(bytes);
 });
+/** 16-hex okfit digest (spec section 3): the first 64 bits of SHA-256. */
+const digest = (text) => Effect.map(digestFull(text), (hex) => hex.slice(0, 16));
+const bodyDigest = (source) => digest(body(source));
+const contentDigest = (raw, source) => digest(Canonical.contentInput(raw, source));
 /** The text before the first `@` (the whole value when there is none), or undefined when empty or containing whitespace. */
 const localPartOf = (email) => {
 	if (email === void 0) return void 0;
@@ -75,8 +101,8 @@ const humanActorId = (identity, humans) => {
 	const slug = slugOf(identity.name);
 	const candidates = [local, slug].filter((candidate) => candidate !== void 0).map((candidate) => candidate.toLowerCase());
 	for (const entry of humans) {
-		if (!entry.startsWith(HUMAN_PREFIX)) continue;
-		if (candidates.includes(entry.slice(6).toLowerCase())) return Option.some(entry);
+		if (!entry.startsWith(HUMAN_PREFIX) || Actor.isPattern(entry)) continue;
+		if (candidates.includes(entry.slice(6).toLowerCase())) return Option.some(decodeActor(entry));
 	}
 	if (local !== void 0) return Option.some(decodeActor(`${HUMAN_PREFIX}${local}`));
 	if (slug !== void 0) return Option.some(decodeActor(`${HUMAN_PREFIX}${slug}`));
@@ -104,7 +130,7 @@ const uncommitted = (reason) => ({
 *
 * @public
 */
-var Derivation = class {
+var Derivation = class Derivation {
 	constructor() {}
 	/**
 	* `FrontmatterSource.split(text).body`, then CRLF and lone CR to LF, then trailing whitespace at end of
@@ -112,12 +138,33 @@ var Derivation = class {
 	*/
 	static body = body;
 	/**
-	* Lowercase 64-char hex sha256 of `Derivation.body(text)`, through `effect`'s platform-agnostic
-	* `Crypto` service (issue #19). Same normalization as `body`, so a frontmatter-only edit or a
-	* `core.autocrlf` worktree never changes the digest.
+	* Full lowercase 64-char hex sha256 of a string. Tests only.
+	*
+	* @internal
+	*/
+	static digestFull = digestFull;
+	/**
+	* The okfit digest of a string: the first 16 lowercase hex characters of its SHA-256, through
+	* `effect`'s platform-agnostic `Crypto` service.
+	*/
+	static digest = digest;
+	/**
+	* 16-hex digest of `Derivation.body(source)` (issue #19). Same normalization as `body`, so a
+	* frontmatter-only edit or a `core.autocrlf` worktree never changes the digest.
 	*/
 	static bodyDigest = bodyDigest;
 	/**
+	* The body digest recorded for a generated concept: `integrity.generated.body`, else the legacy
+	* `generated.body_sha256` cut to its first 16 hex characters. `undefined` when neither is present.
+	* Pure; every "is the stamped body still current" comparison reads through this.
+	*/
+	static recordedBody = (concept) => concept.frontmatter.integrity?.generated?.body ?? concept.frontmatter.generated?.body_sha256?.slice(0, 16);
+	/**
+	* 16-hex digest of the canonical content input (`Canonical.contentInput`): authored frontmatter
+	* plus the normalised body, insensitive to style, key order and CRLF.
+	*/
+	static contentDigest = contentDigest;
+	/**
 	* Spec 5.4 rule 2 as P-2 (DERIVE option C). Steps:
 	*  1. `root = Git.repoRoot(dirname(file))`: a file outside any repository surfaces `NotARepositoryError`;
 	*     submodules and worktrees work because the question is asked from the file's directory (P-39).
@@ -172,14 +219,15 @@ var Derivation = class {
 	});
 	/**
 	* P-13 / P-14, pure. Candidates: the email local part (returned as written, lower-cased only for matching)
-	* and the `user.name` slug. Order, first hit wins: (1) a `human:` entry of `humans` whose id equals a
-	* candidate case-insensitively, returned verbatim; (2) `human:<local>`; (3) `human:<slug>`; (4) none.
+	* and the `user.name` slug. Order, first hit wins: (1) a literal `human:` entry of `humans` (glob entries,
+	* those with `*` or `?`, are skipped) whose id equals a candidate case-insensitively, returned verbatim; (2) `human:<local>`; (3) `human:<slug>`; (4) none.
 	* The result is branded through core's `Actor` codec and always passes it.
 	*/
 	static humanActorId = humanActorId;
 	/**
 	* Spec 5.4 rule 1 (P-16, P-45). `"agent"`: `config.actors.agent`, else {@link AgentActorUnconfiguredError}
-	* (P-17). `"human"`: `Git.configGet(cwd, "user.name")` and `Git.configGet(cwd, "user.email")` in merged
+	* (P-17). `"human"`: first `Git.configGet(cwd, "okfit.actor")`, which wins when set and must be a
+	* `human:<id>` with no `@` or glob ({@link ActorConfigInvalidError} otherwise), returned in the spelling of an exact `[actors].humans` entry that equals it case-insensitively (P-14); else `Git.configGet(cwd, "user.name")` and `Git.configGet(cwd, "user.email")` in merged
 	* scope (P-15) through {@link Derivation.humanActorId}; none is {@link HumanActorUnresolvedError}.
 	* Answers only "who is writing now" (P-40).
 	*/
@@ -190,6 +238,13 @@ var Derivation = class {
 			return agent;
 		}
 		const git = yield* Git;
+		const chosen = Option.getOrUndefined(yield* git.configGet(options.cwd, "okfit.actor"));
+		if (chosen !== void 0) {
+			if (!(Schema.is(Actor)(chosen) && Actor.isHuman(chosen) && !chosen.includes("@") && !Actor.isPattern(chosen))) return yield* new ActorConfigInvalidError({ value: chosen });
+			const lower = chosen.toLowerCase();
+			const spelled = (options.config.actors?.humans ?? []).find((entry) => !Actor.isPattern(entry) && entry.toLowerCase() === lower);
+			return spelled === void 0 ? chosen : decodeActor(spelled);
+		}
 		const name = Option.getOrUndefined(yield* git.configGet(options.cwd, "user.name"));
 		const email = Option.getOrUndefined(yield* git.configGet(options.cwd, "user.email"));
 		const identity = {
@@ -204,6 +259,22 @@ var Derivation = class {
 		return resolved.value;
 	});
 	/**
+	* The human allowed to verify now: {@link Derivation.generatedBy} for a human
+	* writer, then the `[actors].humans` allow-list (`Actor.allowed`): empty or
+	* absent allows anyone, otherwise the actor must match an entry or this fails
+	* {@link HumanActorNotAllowedError}. `okfit verify`, `--revoke` and the LSP
+	* verify actions all resolve through this.
+	*/
+	static verifier = Effect.fn("Derivation.verifier")(function* (options) {
+		const actor = yield* Derivation.generatedBy({
+			writer: "human",
+			cwd: options.cwd,
+			config: options.config
+		});
+		if (!Actor.allowed(actor, options.config.actors?.humans ?? [])) return yield* new HumanActorNotAllowedError({ actor });
+		return actor;
+	});
+	/**
 	* P-19, pure: `from` plus `config.lifecycle.default_stale_after`, falling back to `OkfitConfig.DEFAULTS`'
 	* 90 days. `from` is the caller's: `generated.at` when committed, else its own `now`.
 	*/
@@ -211,4 +282,4 @@ var Derivation = class {
 };
 
 //#endregion
-export { AgentActorUnconfiguredError, Derivation, HumanActorUnresolvedError };
+export { ActorConfigInvalidError, AgentActorUnconfiguredError, Derivation, HumanActorNotAllowedError, HumanActorUnresolvedError };

package/Provenance.js

@@ -12,17 +12,20 @@ const encodeAt = Schema.encodeSync(Timestamp);
 * like every other lint (S-7). `Profile.check` and `ProfileDiagnosticCode`
 * are unchanged.
 *
-* Two tiers per concept (issue #19, body-digest design): when
-* `generated.body_sha256` is present, drift is decided ENTIRELY by comparing it to
+* Two tiers per concept (issue #19, body-digest design): when a body digest
+* is recorded (`integrity.generated.body`, else the 16-hex prefix of a legacy
+* `generated.body_sha256`, via `Derivation.recordedBody`), drift is decided
+* ENTIRELY by comparing it to
 * `Derivation.bodyDigest` of the concept's current source -- no git call at
 * all, so this works for a dirty worktree too (that is the point: an edited
 * body is caught immediately, before it is even committed) and survives a
 * squash/rebase merge that only rewrites commit dates, since the body
-* itself, and therefore its digest, never changed. When `body_sha256` is
-* absent (an un-migrated concept), this falls back to the original
+* itself, and therefore its digest, never changed. When no digest is recorded
+* at all (a concept `okfit sync` has never stamped), this falls back to the original
 * git-derived date comparison against `Derivation.generatedAt`, preserving
 * `--skip-provenance`'s meaning for bundles that have not run `okfit sync`
-* since this field was introduced.
+* since the digest was introduced. The drift message names the field the
+* recorded value came from, so a legacy concept reads `generated.body_sha256`.
 *
 * The tier-2 fallback returns `[]` the moment a `NotARepositoryError`
 * surfaces: a bundle outside git has nothing to derive for any concept still
@@ -40,8 +43,8 @@ const encodeAt = Schema.encodeSync(Timestamp);
 * calling at all; the two agree by construction (both skip the walk).
 *
 * A third, optional options argument carries `skipGitTier`: when `true`, a
-* concept that falls through to tier 2 (no `generated.body_sha256`
-* recorded) is skipped entirely -- no `Derivation.generatedAt` call, no
+* concept that falls through to tier 2 (no body digest recorded) is
+* skipped entirely -- no `Derivation.generatedAt` call, no
 * git spawn at all -- while tier 1 still runs, unaffected, for every
 * concept that DOES carry a digest. This is a runtime skip, not a
 * type-level narrowing: the R channel still lists `Git | GitHistory` even
@@ -72,11 +75,13 @@ var Provenance = class {
 		};
 		for (const [, concept] of bundle.concepts) {
 			if (concept.frontmatter.generated === void 0) continue;
-			const recordedDigest = concept.frontmatter.generated.body_sha256;
+			const recordedDigest = Derivation.recordedBody(concept);
 			if (recordedDigest !== void 0) {
 				const currentDigest = yield* Derivation.bodyDigest(concept.document.source);
 				if (currentDigest === recordedDigest) continue;
-				pushDrift(concept.path, `the body has changed since generated.at was last stamped: generated.body_sha256 is ${recordedDigest}, the current body hashes to ${currentDigest}`, DiagnosticRange.forFrontmatterPath(concept.document, ["generated", "at"]));
+				const legacy = concept.frontmatter.generated.body_sha256;
+				const recordedAs = concept.frontmatter.integrity?.generated?.body === void 0 && legacy !== void 0 ? `generated.body_sha256 is ${legacy}` : `integrity.generated.body is ${recordedDigest}`;
+				pushDrift(concept.path, `the body has changed since generated.at was last stamped: ${recordedAs}, the current body hashes to ${currentDigest}`, DiagnosticRange.forFrontmatterPath(concept.document, ["generated", "at"]));
 				continue;
 			}
 			if (skipGitTier) continue;

package/Publications.js

@@ -0,0 +1,135 @@
+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 current = typeof entry.body === "string" && entry.body !== "" ? entry.body : void 0;
+		const legacy = typeof entry.body_sha256 === "string" && entry.body_sha256 !== "" ? entry.body_sha256.slice(0, 16) : void 0;
+		const digest = current ?? legacy;
+		out.push(digest === void 0 ? {
+			index,
+			path: entry.path
+		} : {
+			index,
+			path: entry.path,
+			body: 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 `renders[].body`. 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 } 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 === void 0) {
+					stale.push(`${sourceId} (never stamped)`);
+					continue;
+				}
+				if ((yield* Derivation.bodyDigest(source.document.source)) !== entry.body) 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

@@ -49,7 +49,7 @@ kind = "path"
 
 [types.Decision]
 description = "A choice made, the alternatives rejected, and why."
-guidance = "Never edit a stable Decision; deprecate it and write a new one that names it in supersedes. A Decision counts as settled only once a human has verified it."
+guidance = "Edit a Decision when the choice still stands and its text has drifted or is incomplete; the edit voids its verification until a human verifies it again. Deprecate it and write a successor that names it in supersedes only when the choice itself changes and its history matters."
 require_verified = true
 
 [types.Decision.fields.supersedes]
@@ -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."
 
@@ -242,8 +290,8 @@ Each directory carries its own `index.md`. What `okfit init` writes into these f
 - **`generated.at` is the author date, not the stamp date (P-4).** Walking a path's git history newest-first, the commit that changed the body is the one whose blob first differs from its predecessor's; that commit's *author* date (`%aI`) is `generated.at`. Its committer date, author name, and author email are carried on the result for callers that want a history-based policy later, but `generated.at` itself is never the date of a later frontmatter-only stamp.
 - **The path log is `@effected/git`'s `Git.log(cwd, { paths: [path], follow: true, firstParentDiffMerges: true })` (P-5, amended P-46, decision 56).** `firstParentDiffMerges` surfaces a conflict-resolving merge whose blob differs from both parents (probed on git 2.54.0), which plain `--follow` can omit and which would otherwise attribute that body change to the wrong commit. `Git.log`'s unconditional `-z` makes `--name-only` emit paths raw — no C-style quoting — so no `core.quotePath` override is needed and a path containing a space, a quote, or a newline round-trips verbatim. The dirty check compares the worktree body against `Git.show(root, "HEAD", path)`, never against the newest log entry. `--follow`'s rename detection can itself stop at a commit that renames a file and rewrites its content enough that git no longer treats it as a continuation of the same history; when that happens, `generated.at` answers that rename commit rather than an older one.
 - **Uncommitted is the caller's to interpret (P-10).** `Derivation.generatedAt` reports `{ _tag: "uncommitted", reason: "untracked" | "dirty" | "unborn" }` and never substitutes `now`. The recommended policy, followed by the snippet below: omit `generated.at` entirely until the body is committed.
-- **The body digest answers "has the body changed", where dates cannot (issue #19).** `Derivation.bodyDigest(text)` is a sha256, hex-encoded, over the same normalised body `Derivation.body` produces (CRLF and lone CR to LF, trailing whitespace at end of text removed), so a `core.autocrlf` worktree and a trailing-newline change hash identically and a frontmatter-only edit does not move the digest at all. It is computed through effect's own `Crypto` service rather than `node:crypto`, so it carries `Crypto.Crypto` in its R channel; `NodeServices.layer` already supplies it wherever this package is used. `okfit sync` records it as `generated.body_sha256` — okfit's own extension key, not an OKF v0.2 field — and `Provenance.lint` compares it. Git cannot make this judgement on its own: the stamp lives in the same blob as the body, so a squash merge (one new commit carrying both) is indistinguishable by history from a body edited without a re-stamp.
-- **Human actor resolution (P-13).** Given git identity `{ name?, email? }` and `config.actors.humans`, the first hit wins: (1) a `human:<id>` entry whose id matches the email's local part or the name's slug, case-insensitively (config spelling returned); (2) `human:<local part>`; (3) `human:<slug of name>`; (4) unresolved. The slug lowercases `name`, replaces runs of whitespace and characters outside `[A-Za-z0-9._-]` with `-`, and trims leading and trailing `-`.
+- **The body digest answers "has the body changed", where dates cannot (issue #19).** `Derivation.bodyDigest(text)` is a 16-hex SHA-256 prefix over the same normalised body `Derivation.body` produces (CRLF and lone CR to LF, trailing whitespace at end of text removed), so a `core.autocrlf` worktree and a trailing-newline change hash identically and a frontmatter-only edit does not move the digest at all. It is computed through effect's own `Crypto` service rather than `node:crypto`, so it carries `Crypto.Crypto` in its R channel; `NodeServices.layer` already supplies it wherever this package is used. `okfit sync` records it as `integrity.generated.body` — okfit's own extension key, not an OKF v0.2 field — and `Provenance.lint` compares it. Git cannot make this judgement on its own: the stamp lives in the same blob as the body, so a squash merge (one new commit carrying both) is indistinguishable by history from a body edited without a re-stamp.
+- **Human actor resolution (P-13).** Given git identity `{ name?, email? }` and `config.actors.humans`, the first hit wins: (1) `git config okfit.actor`, which must be a `human:<id>` with no `@` and no `*` or `?` (`ActorConfigInvalidError` otherwise); (2) a literal `human:<id>` entry (glob entries are skipped) whose id matches the email's local part or the name's slug, case-insensitively (config spelling returned); (3) `human:<local part>`; (4) `human:<slug of name>`; (5) unresolved (`HumanActorUnresolvedError`). `Derivation.verifier` runs that resolution and then checks the `[actors].humans` allow-list with core's `Actor.allowed`: an empty or absent list allows anyone, a non-empty one fails with `HumanActorNotAllowedError`, which is what `okfit verify`, `--revoke` and the language server's verify actions surface. okfit never stores an email; the trust signal reports `actor-not-allowed` (a `DriftReason`) for a verifier outside the list. The slug lowercases `name`, replaces runs of whitespace and characters outside `[A-Za-z0-9._-]` with `-`, and trims leading and trailing `-`.
 - **Identity is read at merged config scope (P-15).** `Derivation.generatedBy` calls `Git.configGet(cwd, "user.name")` and `Git.configGet(cwd, "user.email")` with no `scope` option. Environment overrides (`GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `EMAIL`, `user.useConfigOnly`) are out of scope for phase 1.
 - **`stale_after` is pure addition (P-19).** `Derivation.staleAfter(from, config)` is `from + (config.lifecycle?.default_stale_after ?? OkfitConfig.DEFAULTS.lifecycle.default_stale_after)`, falling back to 90 days. `from` should be `generated.at` when the provenance is `committed`, otherwise the caller's own `now`; re-stamp whenever `generated.at` changes.
 
@@ -265,7 +313,7 @@ Frontmatter serialisation, the uncommitted policy's enforcement, `now`, layer co
 lint (`lint.generated_at_drift`, config default `"warn"`), and it runs in
 two tiers (issue #19).
 
-Tier 1 applies to a concept that records `generated.body_sha256`: the
+Tier 1 applies to a concept that records `integrity.generated.body`: the
 recorded digest is compared against
 `Derivation.bodyDigest(concept.document.source)`, a pure comparison over
 text already in memory with no git call and no filesystem read. Drift here

package/SoftwareProject.js

@@ -1,3 +1,4 @@
+import { DOCS_PRESETS } from "./presets/index.js";
 import { DiagnosticRange } from "@okfit/core";
 
 //#region src/SoftwareProject.ts
@@ -57,7 +58,7 @@ const config = {
 		},
 		Decision: {
 			description: "A choice made, the alternatives rejected, and why.",
-			guidance: "Never edit a stable Decision; deprecate it and write a new one that names it in supersedes. A Decision counts as settled only once a human has verified it.",
+			guidance: "Edit a Decision when the choice still stands and its text has drifted or is incomplete; the edit voids its verification until a human verifies it again. Deprecate it and write a successor that names it in supersedes only when the choice itself changes and its history matters.",
 			require_verified: true,
 			fields: { supersedes: {
 				description: "The Decision this one replaces.",
@@ -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
 };