Fix scaffold Astro template for real authoring (adversarial review)

An adversarial review of the scaffold surfaced four defects the example bundle
dodged — all verified by scaffolding a KB and running `astro build`:

1. (high) Nested index.md/log.md crashed the build: the glob excluded only the
   root-level reserved files, but the toolkit reserves them at any depth. Use
   '!**/index.md' / '!**/log.md'.
2. (high) In-body `.md` cross-links rendered verbatim -> 404 (and the bundled
   author-concept skill teaches root-absolute `.md` links). Add a base-aware
   remark-lokf-links plugin that rewrites relative/root-absolute `.md` links to
   their page routes under the site base.
3. (med) Bundle-relative relation targets (valid LOKF, resolved by the toolkit)
   dropped graph edges and rendered broken links. Add resolveRef() mirroring
   Bundle.resolve, applied in relationsOf() and graph.jsonld.
4. (low) IRI drift: the glob loader slugified ids and ignored an explicit
   frontmatter `id`. Preserve the literal path via generateId; honor an
   absolute `id` in iriOf; order graph.jsonld so iriOf wins.

Verified end-to-end on an adversarial scaffold (nested index + relative &
root-absolute relations + in-body `.md` links): build succeeds, all 3 edges
resolve, links are base-aware, 0 stray `.md` hrefs. 133 tests + a new regression
guard.

Author: nicholsn

src/lokf/templates/kb/astro.config.mjs

@@ -1,16 +1,21 @@
 // @ts-check
 import { defineConfig } from 'astro/config';
+import remarkLokfLinks from './remark-lokf-links.mjs';
 import remarkStripLeadingTitle from './remark-strip-leading-title.mjs';
 
 // `site` + `base` are derived from the bundle's base_iri, so the site works
 // both on a custom domain (base "/") and as a GitHub *project* page
 // (base "/<repo>"). Internal links use the href() helper in src/lib/lokf.ts,
-// which prefixes import.meta.env.BASE_URL. The remark plugin drops a concept
-// body's redundant leading `# Title` (the layout renders it from frontmatter).
+// which prefixes import.meta.env.BASE_URL. The remark plugins rewrite concept
+// `.md` cross-links to base-aware routes and drop a body's redundant leading
+// `# Title` (the layout renders it from frontmatter).
 export default defineConfig({
   site: '__KB_SITE__',
   base: '__KB_BASE__',
   markdown: {
-    remarkPlugins: [remarkStripLeadingTitle],
+    remarkPlugins: [
+      [remarkLokfLinks, { base: '__KB_BASE__' }],
+      remarkStripLeadingTitle,
+    ],
   },
 });

src/lokf/templates/kb/remark-lokf-links.mjs

@@ -0,0 +1,37 @@
+import path from 'node:path';
+
+/**
+ * Concept bodies link to peers with markdown `.md` paths — relative
+ * (`../glossary/active-user.md`) or bundle-root-absolute
+ * (`/tables/user-events.md`, the form the author-concept skill teaches).
+ * Rewrite them to the concept's site route, prefixed with the site's base so
+ * they work on a GitHub *project* page under `/<repo>/`. External, mailto, and
+ * anchor links are left alone; links outside `knowledge/` are left alone.
+ *
+ * `base` is the Astro `base` (e.g. `/my-kb` or `/`), injected from the config.
+ */
+const KNOWLEDGE_ROOT = path.join(process.cwd(), 'knowledge');
+
+function walk(node, fn) {
+  if (!node || typeof node !== 'object') return;
+  if (node.type === 'link') fn(node);
+  if (Array.isArray(node.children)) for (const c of node.children) walk(c, fn);
+}
+
+export default function remarkLokfLinks({ base = '/' } = {}) {
+  const prefix = base === '/' ? '' : base.replace(/\/$/, '');
+  return (tree, file) => {
+    const filePath = file.path || (file.history && file.history[0]);
+    const dir = filePath ? path.dirname(filePath) : KNOWLEDGE_ROOT;
+    walk(tree, (node) => {
+      const url = node.url || '';
+      if (!url.endsWith('.md') || /^(https?:|mailto:|#)/.test(url)) return;
+      const abs = url.startsWith('/')
+        ? path.join(KNOWLEDGE_ROOT, url.replace(/^\//, ''))
+        : path.resolve(dir, url);
+      const rel = path.relative(KNOWLEDGE_ROOT, abs).replace(/\.md$/, '');
+      if (rel.startsWith('..')) return;
+      node.url = prefix + '/' + rel.split(path.sep).join('/');
+    });
+  };
+}

src/lokf/templates/kb/src/content.config.ts

@@ -5,13 +5,19 @@ import { glob } from 'astro/loaders';
  * The `knowledge/` directory at the repo root IS the content: a LOKF bundle of
  * markdown concept files. OKF requires only `type`, and consumers must
  * tolerate unknown keys — so the schema validates the common fields and
- * passes everything else through. `index.md` and `log.md` are reserved bundle
- * files (OKF §3), not concepts.
+ * passes everything else through.
  */
 const knowledge = defineCollection({
   loader: glob({
-    pattern: ['**/*.md', '!index.md', '!log.md'],
+    // `index.md` and `log.md` are reserved bundle files (OKF §3) at ANY depth —
+    // the toolkit ignores them everywhere, so exclude them everywhere (`**`
+    // matches zero segments too, keeping the root files excluded).
+    pattern: ['**/*.md', '!**/index.md', '!**/log.md'],
     base: './knowledge',
+    // Preserve the literal relative path as the entry id (Astro's default
+    // slugifies it), so a concept's IRI (base_iri + id) matches the toolkit's
+    // concept_id exactly — no case/underscore drift between site and graph.
+    generateId: ({ entry }) => entry.replace(/\.md$/, ''),
   }),
   schema: z
     .object({

src/lokf/templates/kb/src/lib/lokf.ts

@@ -29,7 +29,20 @@ export const REL_LABEL: Record<string, string> = {
 export const href = (path: string) =>
   import.meta.env.BASE_URL.replace(/\/$/, '') + '/' + path.replace(/^\//, '');
 
-export const iriOf = (e: Concept) => BASE_IRI + e.id;
+/**
+ * Resolve a relation target to a full IRI — mirrors the toolkit's
+ * `Bundle.resolve`: absolute IRIs (http(s)/urn) pass through; a bundle-relative
+ * Concept ID (`glossary/active-user` or `/glossary/active-user`) hangs off the
+ * base IRI so it matches the concept's own `iriOf`.
+ */
+export const resolveRef = (ref: string) =>
+  /^(https?:|urn:)/.test(ref) ? ref : BASE_IRI + ref.replace(/^\//, '');
+
+/** A concept's IRI: an explicit absolute frontmatter `id`, else base + path. */
+export const iriOf = (e: Concept) => {
+  const id = (e.data as Record<string, unknown>).id;
+  return typeof id === 'string' && /^(https?:|urn:)/.test(id) ? id : BASE_IRI + e.id;
+};
 export const hrefOf = (e: Concept) => href(e.id);
 export const titleOf = (e: Concept) => e.data.title ?? e.id;
 
@@ -48,11 +61,11 @@ export function relationsOf(e: Concept): { slot: string; target: string }[] {
     const v = d[slot];
     if (v === undefined) continue;
     for (const target of Array.isArray(v) ? v : [v]) {
-      if (typeof target === 'string') out.push({ slot, target });
+      if (typeof target === 'string') out.push({ slot, target: resolveRef(target) });
     }
   }
   for (const rel of (d.relations as { predicate?: string; target?: string }[] | undefined) ?? []) {
-    if (rel?.predicate && rel?.target) out.push({ slot: rel.predicate, target: rel.target });
+    if (rel?.predicate && rel?.target) out.push({ slot: rel.predicate, target: resolveRef(rel.target) });
   }
   return out;
 }

src/lokf/templates/kb/src/pages/graph.jsonld.ts

@@ -1,5 +1,5 @@
 import type { APIRoute } from 'astro';
-import { loadBundle, iriOf } from '../lib/lokf';
+import { loadBundle, iriOf, resolveRef, RELATION_SLOTS } from '../lib/lokf';
 
 /** The LOKF JSON-LD context published by the lokf project. */
 const CONTEXT =
@@ -12,11 +12,19 @@ const CONTEXT =
  */
 export const GET: APIRoute = async () => {
   const { concepts } = await loadBundle();
-  const graph = concepts.map((c) => ({
-    id: iriOf(c),
-    ...(c.data as Record<string, unknown>),
-    ...(c.body ? { body: c.body } : {}),
-  }));
+  const graph = concepts.map((c) => {
+    const data = { ...(c.data as Record<string, unknown>) };
+    // Resolve bundle-relative relation targets to full IRIs so the RDF edges
+    // are unambiguous (mirrors the toolkit); `id` = the concept's own IRI.
+    for (const slot of RELATION_SLOTS) {
+      const v = data[slot];
+      if (v === undefined) continue;
+      data[slot] = (Array.isArray(v) ? v : [v]).map((t) =>
+        typeof t === 'string' ? resolveRef(t) : t,
+      );
+    }
+    return { ...data, id: iriOf(c), ...(c.body ? { body: c.body } : {}) };
+  });
   const doc = { '@context': CONTEXT, '@graph': graph };
   return new Response(JSON.stringify(doc, null, 2), {
     headers: { 'Content-Type': 'application/ld+json; charset=utf-8' },

tests/test_scaffold.py

@@ -88,3 +88,17 @@ def test_refuses_file_target(tmp_path):
     (tmp_path / "kb").write_text("i am a file")
     with pytest.raises(FileExistsError):
         scaffold.new("kb", path=tmp_path)
+
+
+def test_template_handles_real_authoring(tmp_path):
+    """Guards the adversarial-review fixes: nested reserved files, .md links,
+    relative relation targets, and literal-path ids."""
+    root = scaffold.new("kb", path=tmp_path)
+    cfg = (root / "src/content.config.ts").read_text()
+    assert "'!**/index.md'" in cfg and "'!**/log.md'" in cfg  # reserved at any depth
+    assert "generateId" in cfg                                # literal-path ids, no slugify
+    astro = (root / "astro.config.mjs").read_text()
+    assert "remarkLokfLinks" in astro                         # .md cross-links -> routes
+    assert (root / "remark-lokf-links.mjs").exists()
+    lib = (root / "src/lib/lokf.ts").read_text()
+    assert "resolveRef" in lib                                # relative relation targets