lowkey-doc 0.0.0-stage → 1.0.1

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "lowkey-doc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Render a folder of Markdown into one self-contained documentation dashboard, with flowcharts and ER diagrams that stay readable when they get dense.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lorebalbo/lowkey-doc.git"
+  },
+  "homepage": "https://github.com/lorebalbo/lowkey-doc#readme",
+  "bugs": {
+    "url": "https://github.com/lorebalbo/lowkey-doc/issues"
+  },
+  "type": "module",
+  "bin": {
+    "lowkey-doc": "bin/lowkey-doc.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "commands",
+    "licenses",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "start": "node bin/lowkey-doc.mjs",
+    "build": "node bin/lowkey-doc.mjs --no-open",
+    "check": "node test/smoke.mjs"
+  },
+  "keywords": [
+    "documentation",
+    "markdown",
+    "mermaid",
+    "elk",
+    "flowchart",
+    "er-diagram",
+    "static-site",
+    "offline"
+  ],
+  "license": "MIT",
+  "dependencies": {}
+}

package/skills/audit-docs/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: audit-docs
+description: Audit project documentation and return a structured audit report. Use when asked to review, audit, or sanity-check docs — "audit the docs", "review DOCS/3", "is this document clear enough". Read-only; it never edits the documents.
+---
+
+# Auditing documentation
+
+You are a documentation auditor. Audit the document(s) you were pointed at and return a
+structured report. **Never edit the documents** — this produces a report only.
+
+## What to audit
+
+Whatever the invocation named. If nothing was named, ask which document(s) to audit, or take the
+obvious target: the folder `docs.config.json` sets as `"docs"`, else `docs/`, else `README.md`.
+If it is a path, read it with your file tools first. If it is pasted text, audit that text.
+
+## Context
+
+This documentation describes **what** the project should do, not necessarily **how** it will be
+implemented. Some sections may incidentally mention implementation details — acceptable as long as
+the intent of the document stays outcome-focused.
+
+## Audit criteria
+
+### 1. Clarity
+- Is each section unambiguous? Could two people read it and reach different conclusions about what
+  is expected?
+- Flag vague language ("somehow", "might", "as needed", "etc.") that leaves outcomes undefined.
+
+### 2. Completeness
+- Gaps: missing sections, undefined terms, referenced concepts that are never explained.
+- Are edge cases and failure states addressed?
+
+### 3. Consistency
+- Does the document contradict itself?
+- Are terms used consistently, or does one concept appear under several names?
+
+### 4. Scope integrity
+- The document should describe *what*, not *how*.
+- Flag sections that dive into implementation specifics in a way that would constrain the work
+  unnecessarily — unless the constraint is intentional and justified.
+
+### 5. Actionability
+- Can a reader tell exactly what success looks like?
+- Are acceptance criteria or expected outcomes clearly stated or implied?
+
+### 6. Structure
+- Is it logically organised? Does the section order make sense?
+- Anything that should be merged, split, or reordered?
+
+### 7. Cross-links and diagrams
+- Does every "see below" / "see the other doc" resolve to an actual link?
+- Does each flow that needs a diagram have one, and does the diagram agree with the prose beside it?
+- Are edge labels short enough to read — a label of a dozen words or more is prose that escaped
+  into the diagram.
+
+### 8. Duplication across documents
+- Does this document restate something another document owns? Each topic should have exactly one
+  owning file; a restatement is a future contradiction.
+
+## Output
+
+**Summary** — 2–4 sentences on overall quality.
+
+**Issues** — for each: location (section name or quote), category (Clarity / Completeness /
+Consistency / Scope integrity / Actionability / Structure / Links / Duplication), severity
+(Critical / Major / Minor), the problem, and a suggested fix.
+
+**Strengths** — what the documentation does well.
+
+**Recommended next steps** — prioritised.

package/skills/write-doc/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: write-doc
+description: Write a new high-level product document for this project's documentation folder. Use when asked to document a feature, flow, or area for a non-technical reader — "write a doc about X", "document the checkout flow", "add a docs page for onboarding".
+---
+
+# Writing a document
+
+These are **high-level product documents**: plain-language guides to what a person
+experiences, with diagrams anyone can follow. They are not architecture or implementation docs.
+
+Read an existing document in the same folder before writing — match its voice and shape. The
+folder is whatever `docs.config.json` sets as `"docs"` (`docs/` if there is no config).
+
+## Rules
+
+1. **Describe the experience, not the code.** What the user sees, taps, and gets back. No file
+   names, function names, table names, or libraries in the body. If a technical decision must be
+   recorded, put it in an appendix at the very end, clearly marked as direction, not detail.
+2. **Plain language.** Short sentences. Define any term the reader might not know; add a
+   **Quick glossary** at the end if the doc uses more than a couple.
+3. **Diagrams.** Include a Mermaid diagram for every flow, state machine, or set of relationships
+   a diagram would make clearer — not just one per doc. See [Diagrams](#diagrams) below.
+4. **Tables** for "what exists where" / availability comparisons.
+5. **Link every mention.** Any reference to another section, another document, or an open point is
+   a link — never a bare "see below" or "see the other doc". Same-doc:
+   `[the pipeline](#the-shape-of-the-flow)`. Other doc: `[CATALOG](./2.%20CATALOG.md)`. Open point:
+   `[open point](#op-1)`.
+6. **Open points, only if there are any.** A `## Points to evaluate (open considerations)` section
+   at the very bottom, before any appendix. Numbered list, each item anchored with
+   `<a id="op-N"></a>` and starting with a bold one-line title, then what's undecided and the
+   arguments each way. State the baseline behaviour until it's settled. These are questions, not
+   decisions — anything settled belongs in the body.
+
+## Diagrams
+
+Prefer `flowchart TD`; use whatever Mermaid type fits (sequence, state, ER). Label nodes with what
+the *user* does or sees, quote every label, and use `<br/>` for line breaks. A reader with no
+technical background must be able to follow it.
+
+The dashboard re-lays flowcharts and ER diagrams out with ELK, which routes edges at right angles
+and reserves space for every edge label, so a dense chart stays readable without hand-tuning. Two
+things still help it:
+
+- **Name the transition, not the mechanism.** `-->|"tap Save"|` reads; `-->|"POST /parcels"|` does not.
+- **Keep an edge label short.** One short phrase, or two lines split with `<br/>`. A label longer
+  than a dozen words is prose that escaped into the diagram — move it to the paragraph above.
+
+Do not hand-place nodes, add `linkStyle`, or otherwise fight the layout: the dashboard lays the
+chart out itself, and those directives only affect the mermaid fallback.
+
+For an `erDiagram`, the entity is drawn as a table with the keys pinned to its right edge, so:
+
+- **Give the attributes** in a `{ ... }` block whenever the diagram is about a schema. An entity
+  with no block is drawn as a plain named box — right for a diagram about how things relate, wrong
+  for one about what is stored.
+- **Mark the keys** as mermaid spells them — `PK`, `FK`, `UK`, comma-separated for more than one
+  (`uuid parcel_id PK,FK`) — and quote a comment: `string note "free text"`.
+- **Name the role in the reader's words.** `VOYAGE ||--o{ STOWAGE : carries` reads;
+  `: fk_stowage_voyage` does not.
+
+## Shape
+
+```markdown
+# TITLE IN CAPS
+
+> A plain-language guide to <what this covers>. It describes *what the user experiences*
+> at each step, not how the code works. Each flow includes a diagram you can follow
+> without any technical background.
+
+---
+
+## <Orienting section — the mental model, the two or three ideas to keep separate>
+
+## <What exists where — a comparison table, if relevant>
+
+## 1. <First flow>
+   Prose, then a ```mermaid block.
+
+## 2. <Next flow>
+...
+
+## Quick glossary   (if needed)
+
+## Points to evaluate (open considerations)   (if any)
+
+## Appendix — implementation direction   (only if a decision must be recorded)
+```
+
+## Filing
+
+- Name: `<n>. TITLE-IN-CAPS.md` in the documents folder, `<n>` being the next free number.
+  The number drives the order in the sidebar; a document without one sorts after the numbered ones.
+- Sub-folders become their own group in the sidebar, named after the folder — put audits, reviews,
+  and other second-class material in one rather than in the main run.
+- Sections separated by `---`. Wrap prose at ~100 columns.
+- After writing, check whether the document settled anything about the product; if so update the
+  project's context document (usually `0. CONTEXT.md` or `0. ABOUT.md`).

package/src/build.mjs

@@ -0,0 +1,131 @@
+// build.mjs - read the documents, write the page.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { listDocs, assignIds, buildDoc } from './collect.mjs';
+import { vendorMermaid, vendorElk, vendorFont, writeNotices } from './vendor.mjs';
+import { renderPage } from './page.mjs';
+import { DEFAULTS, CLI, VERSION } from './config.mjs';
+
+export async function build(cfg, { open = true, refresh = false, quiet = false } = {}) {
+  const { docs } = collectDocs(cfg);
+
+  const assets = await vendorAssets(cfg, refresh);
+  const html = pageFor(cfg, docs, assets);
+
+  const outFile = path.join(cfg.outDir, 'index.html');
+  fs.writeFileSync(outFile, html);
+
+  const report = {
+    outFile,
+    docs,
+    bytes: fs.statSync(outFile).size,
+    notes: { mermaid: assets.mermaid.note, elk: assets.elk.note, font: assets.font.note },
+  };
+
+  if (!quiet) print(cfg, report);
+  if (open) openInBrowser(outFile);
+  return report;
+}
+
+// The documents half of a build, kept apart from the page so the watcher can
+// redo it after a save without redoing everything. Hand the previous memo back
+// in and only files whose bytes changed are rendered again - unless the set of
+// files itself changed, which can move where any link points, so then every
+// document is rendered again.
+export function collectDocs(cfg, memo = null) {
+  // A folder named on the command line was checked before we got here, so a
+  // missing one is either the configured folder or the default docs/.
+  const shown = (path.relative(process.cwd(), cfg.docsDir) || '.') + path.sep;
+  if (!fs.existsSync(cfg.docsDir)) {
+    throw new Error(cfg.configFile
+      ? path.basename(cfg.configFile) + ' points at ' + shown + ', which does not exist.' +
+        '\nCreate it, or run: ' + CLI + ' init'
+      : 'No ' + shown + ' folder here.' +
+        '\nSet one up with: ' + CLI + ' init' +
+        '\nOr render another folder: ' + CLI + ' <folder>');
+  }
+
+  const entries = listDocs(cfg);
+  if (!entries.length) {
+    throw new Error('Nothing to render in ' + shown + ': add a .md file to it.' +
+      '\nIt reads files ending in ' + [...cfg.extensions, ...Object.keys(cfg.verbatim)].join(', '));
+  }
+
+  // ids first: cross-document links need to resolve to documents not yet built
+  const byFile = assignIds(entries);
+  const layout = JSON.stringify(entries.map((e) => [e.rel, e.group]));
+  const reuse = memo && memo.layout === layout;
+  const files = new Map();
+  const changed = [];
+
+  const docs = entries.map((e) => {
+    const raw = fs.readFileSync(e.abs, 'utf8');
+    const was = reuse && memo.files.get(e.rel);
+    if (was && was.raw === raw) { files.set(e.rel, was); return was.doc; }
+    let doc;
+    try {
+      doc = buildDoc(e, byFile, cfg, raw);
+    } catch (err) {
+      throw new Error(e.rel + ': ' + (err && err.message || err));
+    }
+    files.set(e.rel, { raw, doc });
+    changed.push(doc.id);
+    return doc;
+  });
+
+  return { docs, changed, memo: { layout, files } };
+}
+
+// ELK travels even when the default engine is mermaid: the reader can switch
+// any single diagram over from the page, and that has to work offline too.
+export async function vendorAssets(cfg, refresh = false) {
+  fs.mkdirSync(cfg.outDir, { recursive: true });
+  // The default output folder keeps itself out of git, so no project has to
+  // remember to. A custom `out` may be meant to be committed (GitHub Pages).
+  const ignore = path.join(cfg.outDir, '.gitignore');
+  if (cfg.outDir === path.resolve(cfg.root, DEFAULTS.out) && !fs.existsSync(ignore)) {
+    fs.writeFileSync(ignore, '# written by lowkey-doc: everything here is build output\n*\n');
+  }
+  const assets = {
+    mermaid: await vendorMermaid(cfg.outDir, refresh),
+    elk: await vendorElk(cfg.outDir, refresh),
+    font: await vendorFont(cfg.outDir, refresh),
+  };
+  writeNotices(cfg.outDir);
+  return assets;
+}
+
+export function pageFor(cfg, docs, assets) {
+  return renderPage({
+    cfg, docs,
+    fontCss: assets.font.css,
+    mermaidTag: assets.mermaid.tag,
+    elkTag: assets.elk.tag,
+  });
+}
+
+function print(cfg, r) {
+  const pad = (s, n) => String(s).padEnd(n).slice(0, n);
+  console.log(cfg.title + '  (lowkey-doc ' + VERSION + ')');
+  for (const d of r.docs) {
+    console.log('  ' + String(d.badge).padStart(3) + '  ' + pad(d.title, 38) +
+      String(d.sections.length).padStart(3) + ' sections' +
+      (d.diagrams ? '  ' + d.diagrams + (d.diagrams > 1 ? ' diagrams' : ' diagram') : ''));
+  }
+  console.log('  mermaid: ' + r.notes.mermaid);
+  console.log('  elk:     ' + r.notes.elk);
+  console.log('  font:    ' + r.notes.font);
+  console.log('  -> ' + r.outFile + '  (' + (r.bytes / 1024).toFixed(0) + ' KB)');
+}
+
+// `start` is a cmd built-in rather than a program, so on Windows it has to go
+// through cmd; the empty first argument stops a quoted path being taken for
+// the window title.
+export function openInBrowser(target) {
+  const [cmd, args] = process.platform === 'darwin' ? ['open', [target]]
+    : process.platform === 'win32' ? ['cmd', ['/c', 'start', '""', target]]
+    : ['xdg-open', [target]];
+  execFile(cmd, args, (err) => { if (err) console.error('  (open failed: ' + err.message + ')'); });
+}

package/src/client/api.mjs

@@ -0,0 +1,102 @@
+// api.mjs - the API call blocks, inlined into the page.
+//
+// A call is a box whose header - verb and url - is always shown. A click on
+// the header opens the body, which says what each part of the url is.
+//
+// Folded, the box still answers questions: holding Ctrl - Option on a Mac,
+// the same key the ER diagrams use - with the pointer on a described part of
+// the url shows that part's description, without opening anything. Open, the
+// descriptions are already on screen, so the key does nothing.
+
+export const API_JS = String.raw`
+(function(){
+  var IS_MAC = /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent || '');
+  var TIP_KEY = IS_MAC ? 'Alt' : 'Control';
+  function keyHeld(e){ return IS_MAC ? e.altKey : e.ctrlKey; }
+
+  function setOpen(box, open){
+    box.classList.toggle('is-open', open);
+    var head = box.querySelector('.api-head');
+    if (head && head.hasAttribute('aria-expanded')) head.setAttribute('aria-expanded', open ? 'true' : 'false');
+    hideTip();
+  }
+
+  document.addEventListener('click', function(e){
+    var head = e.target.closest && e.target.closest('.api-head[role=button]');
+    if (!head) return;
+    // a selection being made for a comment is not a click on the header
+    var sel = window.getSelection && window.getSelection();
+    if (sel && !sel.isCollapsed && head.contains(sel.anchorNode)) return;
+    var box = head.closest('.api');
+    setOpen(box, !box.classList.contains('is-open'));
+  });
+  document.addEventListener('keydown', function(e){
+    if (e.key !== 'Enter' && e.key !== ' ') return;
+    var head = e.target.closest && e.target.closest('.api-head[role=button]');
+    if (!head) return;
+    e.preventDefault();
+    var box = head.closest('.api');
+    setOpen(box, !box.classList.contains('is-open'));
+  });
+
+  /* ------------------------------------------------- a part's row */
+
+  function rowOf(part){
+    var box = part.closest('.api');
+    return box && box.querySelector('.api-row[data-part="' + part.getAttribute('data-part') + '"]');
+  }
+
+  /* ------------------------------------------ what a part is, on request */
+
+  var tip = null, tipFor = null, lastPointer = null;
+
+  function target(el){
+    var part = el && el.closest && el.closest('.api-part');
+    return part && !part.closest('.api').classList.contains('is-open') ? part : null;
+  }
+
+  function showTip(part){
+    if (tipFor === part) return;
+    hideTip();
+    var row = rowOf(part);
+    if (!row) return;
+    tipFor = part;
+    part.classList.add('is-asked');
+    tip = document.createElement('div');
+    tip.className = 'dg-tip api-tip';
+    tip.innerHTML = '<div class="api-tip-key">' + row.querySelector('dt').innerHTML + '</div>' +
+      row.querySelector('dd').innerHTML;
+    document.body.appendChild(tip);
+    var box = part.getBoundingClientRect();
+    var vw = document.documentElement.clientWidth, w = tip.offsetWidth, h = tip.offsetHeight;
+    var top = box.top - h - 8;
+    if (top < 8) top = box.bottom + 8;
+    tip.style.left = Math.round(Math.min(Math.max(8, box.left - 12), vw - w - 8)) + 'px';
+    tip.style.top = Math.round(top) + 'px';
+  }
+  function hideTip(){
+    if (tipFor) tipFor.classList.remove('is-asked');
+    tipFor = null;
+    if (tip){ tip.remove(); tip = null; }
+  }
+
+  document.addEventListener('mousemove', function(e){
+    lastPointer = { x: e.clientX, y: e.clientY };
+    var t = keyHeld(e) ? target(e.target) : null;
+    if (t) showTip(t); else if (tip) hideTip();
+  }, { passive: true });
+
+  document.addEventListener('keydown', function(e){
+    if (e.key === TIP_KEY) document.documentElement.classList.add('api-asking');
+    if (e.key !== TIP_KEY || e.repeat || !lastPointer) return;
+    var t = target(document.elementFromPoint(lastPointer.x, lastPointer.y));
+    if (t) showTip(t);
+  });
+  function letGo(){ document.documentElement.classList.remove('api-asking'); hideTip(); }
+  document.addEventListener('keyup', function(e){ if (e.key === TIP_KEY) letGo(); });
+  addEventListener('blur', letGo);
+  addEventListener('scroll', hideTip, { passive: true });
+  document.addEventListener('wheel', hideTip, { passive: true });
+  document.addEventListener('mousedown', hideTip, true);
+})();
+`;