@polycode-projects/the-mechanical-code-talker 1.8.20 → 1.9.1

package/README.md

@@ -334,12 +334,23 @@ reasoning). Design detail and the full fact-count tables are in `archive/PLAN_SE
 ### Memory backends
 
 The default memory backend writes an OWL-labelled JSON file under `.tmct/`.
-Two more exist for a library caller who doesn't want that: `runChat({
-memoryBackend: "memory" })` keeps taught facts in the process only, nothing
-written to disk; `runChat({ memoryBackend: "sqlite" })` persists them to a
-local SQLite file instead. `TMCT_MEMORY_BACKEND=memory|sqlite` does the same
-from the environment. There's no CLI flag yet — this is a library-level
-option for now, newer and less exercised than the default backend.
+Two more exist: `memory` keeps taught facts in the process only, nothing
+written to disk; `sqlite` persists them to a local SQLite file instead
+(`.tmct/memory/graph.sqlite`).
+
+Pick one at init time and it sticks — `tmct init --memory-backend sqlite`
+writes the choice into `tmct.toml`, and every later `tmct chat` in that repo
+uses it with no flag needed:
+
+```bash
+tmct init --memory-backend sqlite     # writes [memory] backend = "sqlite" to tmct.toml
+tmct chat                             # picks it up automatically
+tmct chat --memory-backend memory     # override for just this session
+```
+
+Precedence is `--memory-backend` flag > `TMCT_MEMORY_BACKEND` env > tmct.toml's
+`[memory] backend` > the default. A library caller sets the same thing
+directly: `runChat({ memoryBackend: "sqlite" })`.
 
 Teaching isn't limited to the ACE grammar's fixed shapes. Tell tmct an
 arbitrary fact, like "margo really eats ribs", and it mints a fact you can
@@ -411,6 +422,10 @@ Inside the chat: `/help` lists commands, `/memory` inspects what tmct remembers
 (grouped by OWL class, with provenance and any contradictions), `/exit` leaves.
 `TMCT_GRAPH_FILE` overrides the graph location.
 
+`tmct --help` (or `npm run help` from a clone of this repo) is the full,
+up-to-date flag reference for every subcommand — a bare `npm run` only lists
+script names, so `npm run help` is the documented way in from there.
+
 `tmct init` is the onboarding surface for the repository interface below: it
 creates the `.tmct/` directory, writes the externalized `tmct.toml`
 configuration, seeds the default persona, and records provenance. A host
@@ -435,17 +450,23 @@ tmct init --lexicon <name|path>               # activate a lexicon bundle (never
 tmct init --graph <path> [--graph <path> …]   # set tmct.toml's graph_file/graph_files
 tmct init --config <path>                     # write to an alternate tmct.toml location
 tmct init --persona-size medium|large         # grow the default persona (Small is default)
+tmct init --memory-backend default|memory|sqlite  # write tmct.toml's [memory] backend —
+                                               # every later `tmct chat` here uses it
 
 tmct import --corpus <id|path>                # activate+seed into an ALREADY-initialized
 tmct import --ontology <name|path>            # repo — any combination of these flags in
 tmct import --lexicon <name|path>             # one call. --graph is a DIFFERENT, purely
 tmct import --graph <path>                    # additive op: it appends to graph_files,
                                                # never activates an extensions bundle.
+tmct import --memory-backend default|memory|sqlite  # same knob as `tmct init`, for a
+                                               # repo that's already initialized
 
 tmct chat --graph <path> [--graph <path> …]   # explicit graph file(s) — multiple merge
                                                # (ids that collide across graphs are
                                                # auto-prefixed; see src/graph-merge.mjs)
 tmct chat --config <path>                     # an alternate tmct.toml (a file or a dir)
+tmct chat --memory-backend default|memory|sqlite  # override tmct.toml's backend for
+                                               # just this session
 tmct serve --graph <path> --config <path>     # same two flags, for the HTTP endpoint
 ```
 

package/ROADMAP.md

@@ -32,7 +32,7 @@ getting silently traded away by inherited caution:
 
 ## What's next (feature-shaped — see `HANDOVER.md` for the current task-level list)
 
-- **`PLAN_BREADTH_FIRST_NLU.md`'s own remaining scope** — all six tracks shipped (entity-tie
+- **`archive/PLAN_BREADTH_FIRST_NLU.md`'s own remaining scope** — all six tracks shipped (entity-tie
   ambiguity, router candidate enrichment, `tmct viz` + its embedded chat panel, template-coverage
   harness, alternates-on-hits, canonical representation for the ask/teach lanes — all now in "Current
   capability surface" above). Two named items are satisfied and closed, per their own track's

package/bin/tmct.mjs

@@ -44,6 +44,9 @@ Usage:
                                TMCT_NARRATE=1; toggle mid-session with /narrate on|off)
        [--plain]               force the plain readline shell (the default when
                                stdin/stdout is not a terminal)
+       [--memory-backend <default|memory|sqlite>]  storage backend for taught facts this
+                               session (CLI flag > TMCT_MEMORY_BACKEND env > tmct.toml's
+                               [memory] backend > "default", the flat .tmct/ JSON file)
   tmct memory [--repo <abs>]   what tmct remembers: facts, utterances, sessions,
        [--config <path>]       folded blocks (the /memory chat command, from the shell)
        [--verbose]
@@ -66,11 +69,15 @@ Usage:
                                activates human-large.jsonl (~13,600 facts total,
                                with genuine multi-hop hypernym chains) — additive
                                size tiers of the SAME bundle, not separate personas
+       [--memory-backend <default|memory|sqlite>]  write tmct.toml's [memory] backend
+                               (same flag name as \`tmct chat\`) — a later \`tmct chat\`
+                               in this repo picks it up with no flag needed
   tmct import [--repo <abs>]   activate+seed into an ALREADY-initialized repo (any
        [--corpus <id|path>]    combination of these flags in one call). --graph is a
        [--ontology <name|path>]  DIFFERENT operation from the others: it APPENDS to
        [--lexicon <name|path>]   tmct.toml's graph_files array (multi-graph growth),
        [--graph <path>]        never an extensions-bundle activation.
+       [--memory-backend <default|memory|sqlite>]  same knob as \`tmct init\`
        [--config <path>]
   tmct extend --validate <dir>  validate a third-party extension pack's declared
        [--config <path>]      resources (corpus/lexicon/templates) before activating
@@ -80,8 +87,18 @@ Usage:
        [--config <path>]      bounded, low-trust, retractable entailed facts (never on the chat path)
   tmct viz [--repo <abs>]      write one self-contained, navigable HTML file rendering the
        [--focus <id>]         memory graph: pan/zoom, click a node for its label/class/
-       [--output <path>]      timestamps. Seeds from the most recently created individual
-       [--config <path>]      by default; --output defaults to graph.html in the cwd.
+       [--term <word>]        timestamps. Seeds from the most recently created individual
+       [--depth <n>]          by default (--focus <id> or --term <word> override it);
+       [--limit <n>]          --output defaults to graph.html in the cwd.
+       [--hub-degree <n>]     --depth = max arcs (hops) from the focus node (default 3);
+       [--edge-kind <mode>]   --limit = spiral length, total nodes walked (default 300);
+       [--output <path>]      --hub-degree = stop expanding THROUGH a node above N
+       [--config <path>]      connections, still shows it (default 40); --edge-kind =
+                               meta|relation|both (default both) — which edge kinds the
+                               walk follows (provenance-only, concept-relations-only, or
+                               both — see the page's own edge-kind toggle to change this
+                               live); --term <word> resolves to the Fact(s) whose subject/
+                               object normalizes to that word and seeds from there.
   tmct serve [--repo <abs>]    run the Anthropic Messages API-compatible endpoint
        [--host <h>] [--port <n>]  (POST /v1/messages) over the graph — a deterministic,
        [--graph <path>]        no-LLM "model" a tool-loop client can call; $0 usage.
@@ -96,6 +113,11 @@ In chat: /help lists slash-commands; /exit leaves. Session log → <repo>/.tmct/
 Shared graph-path precedence (chat/serve; see src/cli-args.mjs): --graph flag(s) >
 TMCT_GRAPH_FILE env > tmct.toml graph_file/graph_files > --repo-derived
 <repo>/.tmct/graph.json > git-root/cwd default.
+
+Memory-backend precedence (chat; see src/chat.mjs createSession): --memory-backend
+flag > TMCT_MEMORY_BACKEND env > tmct.toml [memory] backend > "default" (the flat
+.tmct/ JSON file). Set it once with \`tmct init --memory-backend <...>\` and every
+later \`tmct chat\` in that repo picks it up with no flag needed.
 `;
 
 const argv = process.argv.slice(2);
@@ -330,6 +352,7 @@ async function readConfigForRewrite(repoRoot) {
   }
   if (raw?.extensions !== undefined) cfg.extensions = raw.extensions;
   if (raw?.bias !== undefined) cfg.bias = raw.bias;
+  if (raw?.memory?.backend !== undefined) cfg.memory = { ...cfg.memory, backend: raw.memory.backend };
   return { raw, cfg };
 }
 
@@ -459,7 +482,27 @@ async function activatePluggableInput(repoRoot, resolved) {
   if (!seedable) {
     return `activated "${name}" (${entry.kind}) in tmct.toml — no corpus facts to seed for this kind.\n`;
   }
-  const { perBundle } = await seedActiveCorpusEntries(repoRoot, new Map([[name, entry]]));
+  // Backend-aware seeding (same split-brain bug fix as src/init.mjs's own
+  // corpus seed, found in review): `cfg.memory.backend` already reflects
+  // tmct.toml as it stands RIGHT NOW (readConfigForRewrite, above) — which,
+  // for a `tmct init --corpus X --memory-backend sqlite` / `tmct import
+  // --corpus X --memory-backend sqlite` combined call, already carries the
+  // NEW backend (bin/tmct.mjs's init/import handlers write --memory-backend
+  // before running any activation). Resolved via the SAME openMemoryBackend
+  // createSession/initRepo use, so this bundle's facts land in the store a
+  // later `tmct chat` will actually read.
+  const { openMemoryBackend } = await import("../src/memory/core.mjs");
+  const backendChoice = String(cfg.memory?.backend || "").trim().toLowerCase();
+  if (backendChoice === "memory") {
+    return `activated "${name}" (${entry.kind}) in tmct.toml — seeding skipped (memory backend is in-process only, nothing would persist past this command).\n`;
+  }
+  const { dir: memoryDir, close: closeMemoryStore } = await openMemoryBackend(repoRoot, backendChoice);
+  let perBundle;
+  try {
+    ({ perBundle } = await seedActiveCorpusEntries(memoryDir, new Map([[name, entry]])));
+  } finally {
+    await closeMemoryStore();
+  }
   const seeded = perBundle[name];
   if (seeded.error) {
     throw new Error(`could not seed "${name}" — ${seeded.error}`);
@@ -526,12 +569,25 @@ async function main() {
     // TMCT_GRAPH_FILE — see chat.mjs's own docblock at createSession). Omitted from
     // the call entirely when absent, so a plain `tmct chat [--repo]` invocation is
     // byte-identical to before these flags existed.
-    const { repeatedFlag, strFlag } = await import("../src/cli-args.mjs");
+    const { repeatedFlag, strFlag, enumFlag } = await import("../src/cli-args.mjs");
     const graphPaths = repeatedFlag(rest, ["--graph"]);
     const configPath = strFlag(rest, ["--config"]);
+    // `--memory-backend <default|memory|sqlite>`: the CLI's top tier of
+    // createSession's memoryBackend precedence (CLI flag > TMCT_MEMORY_BACKEND
+    // env > tmct.toml's [memory] backend > built-in default — src/cli-args.mjs's
+    // shared precedence order, resolved inside createSession itself). Omitted
+    // when absent so the lower tiers still apply unchanged.
+    let memoryBackend;
+    try {
+      memoryBackend = enumFlag(rest, ["--memory-backend"], ["default", "memory", "sqlite"]);
+    } catch (e) {
+      process.stderr.write(`tmct: ${e?.message || e}\n`);
+      process.exit(2);
+    }
     const extra = {};
     if (graphPaths.length) extra.graphPaths = graphPaths;
     if (configPath) extra.configPath = configPath;
+    if (memoryBackend) extra.memoryBackend = memoryBackend;
     // The shell gate: a real terminal gets the full-screen Ink TUI; `--plain` or a
     // non-TTY stream (pipes, scripts, the test suite) gets the readline shell. Both
     // drive the same createSession sink — only the drawing differs.
@@ -577,7 +633,7 @@ async function main() {
     // subcommand without a --repo flag. It now takes one like every other
     // subcommand, defaulting to cwd exactly as before when absent.
     const rest = process.argv.slice(3);
-    const { strFlag, repeatedFlag } = await import("../src/cli-args.mjs");
+    const { strFlag, repeatedFlag, enumFlag } = await import("../src/cli-args.mjs");
     const { resolve: resolvePath } = await import("node:path");
     const { initRepo, PERSONA_PRESETS } = await import("../src/init.mjs");
 
@@ -589,6 +645,20 @@ async function main() {
     const lexiconVal = strFlag(rest, ["--lexicon"]);
     const graphFlags = repeatedFlag(rest, ["--graph"]);
 
+    // `--memory-backend <default|memory|sqlite>` (PLAN_SEED.md §6's storage-backend
+    // seam, now reachable from `tmct init`): validated BEFORE touching disk, same
+    // discipline as every other pluggable input below. Written into tmct.toml's
+    // `[memory] backend` (src/init.mjs's renderTomlConfig); chat.mjs's
+    // createSession reads it back at CLI-flag > TMCT_MEMORY_BACKEND env >
+    // tmct.toml > default precedence (src/cli-args.mjs's shared precedence order).
+    let memoryBackendVal;
+    try {
+      memoryBackendVal = enumFlag(rest, ["--memory-backend"], ["default", "memory", "sqlite"]);
+    } catch (e) {
+      process.stderr.write(`tmct init: ${e?.message || e}\n`);
+      process.exit(2);
+    }
+
     // Resolve + validate EVERY pluggable input BEFORE touching disk — mirrors
     // `--with-persona`'s own "validate before scaffolding" discipline, and the
     // original `--corpus`'s "unknown id touches nothing" contract.
@@ -650,7 +720,32 @@ async function main() {
       }
     }
 
-    const res = await initRepo(repoRoot, { force: rest.includes("--force"), persona: personaPreset });
+    // `--memory-backend <default|memory|sqlite>`: written EARLY, before
+    // initRepo/any --corpus/--ontology/--lexicon activation below, so every
+    // seed step (initRepo's own corpus seed, AND activatePluggableInput's,
+    // below) sees the FINAL backend choice. A split-brain bug found in
+    // review: writing this AFTER seeding meant corpus facts always landed in
+    // the OLD backend, regardless of this flag. Two cases:
+    //   - tmct.toml doesn't exist yet (the common case): threaded into
+    //     initRepo() as `memoryBackend`, below — written atomically as part
+    //     of the SAME fresh config write persona/corpus-limit already use.
+    //   - tmct.toml already exists and `--force` isn't set (initRepo's own
+    //     "preserve a user's tmct.toml" rule, same as persona): written HERE,
+    //     before initRepo/activation run, so this repo's re-seed (if any) and
+    //     any --corpus/--ontology/--lexicon activation below see it.
+    const forceFlag = rest.includes("--force");
+    if (memoryBackendVal) {
+      const { access } = await import("node:fs/promises");
+      const tomlPath = resolvePath(repoRoot, "tmct.toml");
+      const tomlAlreadyExists = await access(tomlPath).then(() => true, () => false);
+      if (tomlAlreadyExists && !forceFlag) {
+        const { cfg } = await readConfigForRewrite(repoRoot);
+        cfg.memory = { ...(cfg.memory || {}), backend: memoryBackendVal };
+        await writeConfig(repoRoot, cfg);
+      }
+    }
+
+    const res = await initRepo(repoRoot, { force: forceFlag, persona: personaPreset, memoryBackend: memoryBackendVal });
     process.stdout.write(res.message + "\n");
 
     // `--corpus`/`--ontology`/`--lexicon` now mean "activate this bundle and
@@ -689,6 +784,14 @@ async function main() {
       anyActivation = true;
     }
 
+    // `--memory-backend <default|memory|sqlite>`: already WRITTEN by now —
+    // either just above (pre-existing tmct.toml) or inside initRepo() itself
+    // (a fresh write, `memoryBackend` opt) — this just reports it.
+    if (memoryBackendVal) {
+      process.stdout.write(`memory backend set in tmct.toml: ${memoryBackendVal}\n`);
+      anyActivation = true;
+    }
+
     if (anyActivation) return;
 
     if (rest.includes("--detect")) {
@@ -719,7 +822,7 @@ async function main() {
     // additive operation (appendGraphFiles) — it grows tmct.toml's graph_files
     // array, never activates an extensions bundle.
     const rest = process.argv.slice(3);
-    const { strFlag, repeatedFlag } = await import("../src/cli-args.mjs");
+    const { strFlag, repeatedFlag, enumFlag } = await import("../src/cli-args.mjs");
     const { resolve: resolvePath } = await import("node:path");
 
     const repoFlag = strFlag(rest, ["--repo"]);
@@ -729,9 +832,19 @@ async function main() {
     const ontologyVal = strFlag(rest, ["--ontology"]);
     const lexiconVal = strFlag(rest, ["--lexicon"]);
     const graphFlags = repeatedFlag(rest, ["--graph"]);
+    // `--memory-backend <default|memory|sqlite>`: same knob as `tmct init`'s
+    // (consistent name, same [memory] backend tmct.toml field) — lets an
+    // already-initialized repo change its storage backend without a re-init.
+    let memoryBackendVal;
+    try {
+      memoryBackendVal = enumFlag(rest, ["--memory-backend"], ["default", "memory", "sqlite"]);
+    } catch (e) {
+      process.stderr.write(`tmct import: ${e?.message || e}\n`);
+      process.exit(2);
+    }
 
-    if (!corpusVal && !ontologyVal && !lexiconVal && !graphFlags.length) {
-      process.stderr.write("tmct import: needs at least one of --corpus/--ontology/--lexicon/--graph\n");
+    if (!corpusVal && !ontologyVal && !lexiconVal && !graphFlags.length && !memoryBackendVal) {
+      process.stderr.write("tmct import: needs at least one of --corpus/--ontology/--lexicon/--graph/--memory-backend\n");
       process.exit(2);
     }
 
@@ -745,6 +858,19 @@ async function main() {
       process.exit(2);
     }
 
+    // `--memory-backend` is written FIRST, before any --corpus/--ontology/
+    // --lexicon activation below — the same split-brain bug fix as `tmct
+    // init`'s ordering: activatePluggableInput seeds into whichever backend
+    // tmct.toml names AT THE TIME it runs, so `tmct import --corpus aws
+    // --memory-backend sqlite` in one call must have the new backend on disk
+    // BEFORE the aws seed step, not after.
+    if (memoryBackendVal) {
+      const { cfg } = await readConfigForRewrite(repoRoot);
+      cfg.memory = { ...(cfg.memory || {}), backend: memoryBackendVal };
+      await writeConfig(repoRoot, cfg);
+      process.stdout.write(`memory backend set in tmct.toml: ${memoryBackendVal}\n`);
+    }
+
     for (const resolved of [corpusResolved, ontologyResolved, lexiconResolved]) {
       if (!resolved) continue;
       try {
@@ -863,24 +989,45 @@ async function main() {
     // resolveRuntimeConfig: --repo > git root > cwd.
     const rest = process.argv.slice(3);
     const { strFlag, resolveRuntimeConfig } = await import("../src/cli-args.mjs");
-    const { computeVizGraph, renderVizHtml, readAskBundle } = await import("../src/viz.mjs");
+    const { computeVizGraph, renderVizHtml, readAskBundle, readMemoryAskBundle } = await import("../src/viz.mjs");
     const { writeFile } = await import("node:fs/promises");
     const { resolve } = await import("node:path");
+    const numFlag = (name) => {
+      const j = rest.indexOf(name);
+      const v = j !== -1 ? Number(rest[j + 1]) : NaN;
+      return Number.isFinite(v) ? v : undefined;
+    };
     const focus = strFlag(rest, ["--focus"]);
+    const term = strFlag(rest, ["--term"]); // PLAN_VIZ_MEMORY.md: seed via normFactTerm-matched Fact(s), alongside --focus
+    const depth = numFlag("--depth"); // max arcs (hops) from the focus node
+    const nodeLimit = numFlag("--limit"); // spiral length: total nodes walked
+    const hubDegree = numFlag("--hub-degree"); // stop expanding THROUGH a node above N connections
+    const edgeKindModeRaw = strFlag(rest, ["--edge-kind"]);
+    const edgeKindMode = ["meta", "relation", "both"].includes(edgeKindModeRaw) ? edgeKindModeRaw : undefined;
     const outPath = resolve(process.cwd(), strFlag(rest, ["--output", "--out"], "graph.html"));
     const { repo } = await resolveRuntimeConfig({ argv: rest });
-    const vizGraph = await computeVizGraph(repo, focus ? { focus } : {});
-    // The embedded "Ask the graph" chat panel — the real ask.mjs engine,
-    // bundled for the browser (scripts/build-ask-bundle.mjs's checked-in
-    // output). readAskBundle() never throws; an empty string renders a
-    // graph-only page with an honest "chat unavailable" note instead of a
-    // broken one (e.g. a fresh checkout before the bundle's first build).
-    const askBundle = await readAskBundle();
-    const html = renderVizHtml({ ...vizGraph, askBundle });
+    const vizGraph = await computeVizGraph(repo, {
+      ...(focus ? { focus } : {}),
+      ...(!focus && term ? { term } : {}), // --focus takes precedence when both are given
+      ...(depth != null ? { depth } : {}),
+      ...(nodeLimit != null ? { nodeLimit } : {}),
+      ...(hubDegree != null ? { hubDegree } : {}),
+      ...(edgeKindMode ? { edgeKindMode } : {}),
+    });
+    // The embedded "Ask the graph" chat panels — TWO real engines, bundled for
+    // the browser (scripts/build-ask-bundle.mjs's checked-in output): the
+    // code-graph ask.mjs engine, and (PLAN_VIZ_MEMORY.md Bug 1 fix) the
+    // memory-graph factAnswer engine. Neither read*AskBundle() ever throws; an
+    // empty string degrades that ONE engine gracefully rather than breaking
+    // the page (e.g. a fresh checkout before the bundles' first build).
+    const [askBundle, memoryAskBundle] = await Promise.all([readAskBundle(), readMemoryAskBundle()]);
+    const html = renderVizHtml({ ...vizGraph, askBundle, memoryAskBundle });
     await writeFile(outPath, html, "utf8");
+    const chatNote = askBundle || memoryAskBundle
+      ? ` (with the embedded ask-the-graph chat panel${askBundle && memoryAskBundle ? "s" : ""})`
+      : " (no chat panel — run `npm run build:ask-bundle` first)";
     process.stdout.write(
-      `tmct viz — wrote ${vizGraph.nodes.length} node(s), ${vizGraph.edges.length} edge(s) to ${outPath}`
-      + `${askBundle ? " (with the embedded ask-the-graph chat panel)" : " (no chat panel — run `npm run build:ask-bundle` first)"}\n`,
+      `tmct viz — wrote ${vizGraph.nodes.length} node(s), ${vizGraph.edges.length} edge(s) to ${outPath}${chatNote}\n`,
     );
     return;
   }

package/corpus/generated/README.md

@@ -1,6 +1,6 @@
 # corpus/generated/ — mechanically-generated ACE surface variants
 
-`ace-surface-variants.jsonl` — PLAN_BREADTH_FIRST_NLU.md §6a's raw material for
+`ace-surface-variants.jsonl` — archive/PLAN_BREADTH_FIRST_NLU.md §6a's raw material for
 tmct's "richer template/surface-realization variety" goal. Never an LLM, never
 invented text: every row is a real seed sentence with one word swapped for a
 real WordNet synset sibling, or a real sentence's alternate ACE-grammar-
@@ -29,7 +29,7 @@ Every row also carries `provenance` (`wordnet:<synsetId>` or
 
 This corpus is not loaded by `src/chat.mjs`/`src/ask.mjs` or any other
 product code — it is committed raw material, verified by
-`scripts/template-coverage.mjs`, per PLAN_BREADTH_FIRST_NLU.md §6's explicit
+`scripts/template-coverage.mjs`, per archive/PLAN_BREADTH_FIRST_NLU.md §6's explicit
 non-goal. Wiring it into live answer rendering is a separate, future phase.
 
 ## Licence

package/corpus/namenet/LICENSE-NOTICE

@@ -0,0 +1,68 @@
+LICENSE NOTICE — corpus/namenet/namenet.jsonl
+================================================================================
+
+The file namenet.jsonl in this directory is a mechanical, ConceptNet-shape
+conversion of three human-reviewed linking tables (species, taxon-to-common-
+name, occupations) from the Open English Namenet project. It is licensed
+under the Creative Commons Attribution 4.0 International License
+(CC-BY-4.0), NOT under this repository's MPL-2.0.
+
+  https://creativecommons.org/licenses/by/4.0/
+
+License status of the source repository — read this before redistributing
+--------------------------------------------------------------------------
+
+The source repository, globalwordnet/english-namenet, declares NO explicit
+license of its own: no LICENSE file in the checkout, no license statement in
+its README.md, and GitHub's own repository metadata reports `license: null`
+(confirmed 2026-07-12). CC-BY-4.0 above is a CONSERVATIVE CHOICE by this
+repository, matching the license of the Open English WordNet data the source
+CSVs link against (see Attribution below) — it is not a license the
+globalwordnet/english-namenet maintainers have themselves stated. Anyone
+redistributing namenet.jsonl more widely than this repository should seek
+explicit confirmation from the GlobalWordNet team before relying on that
+label.
+
+Attribution
+-----------
+
+This work includes data derived from the Open English Namenet project (an
+extension of Open English WordNet with names drawn from Wikidata), and
+transitively from Open English WordNet itself (CC-BY-4.0) and Wikidata
+(structured data, CC0).
+
+  - Project: https://github.com/globalwordnet/english-namenet
+  - Open English WordNet: https://github.com/globalwordnet/english-wordnet
+  - Wikidata: https://www.wikidata.org/
+
+Source
+------
+
+- Dataset: three reviewed CSVs from a LOCAL, uncommitted checkout of
+  globalwordnet/english-namenet — never vendored into this repository:
+    - species_reviewed.csv (5,101 rows)
+    - taxon2common_reviewed.csv (2,368 rows)
+    - linked_occupations_reviewed.csv (2,193 rows)
+  Every accepted row in all three links a name/label to an Open English
+  WordNet synset or lemma set that a human reviewer confirmed denotes the
+  SAME real-world thing (a species, a folk-taxonomic category, an
+  occupation) — never a broader/narrower or capability relation. See
+  corpus/namenet/generate.mjs's own header comment for the full reasoning
+  behind mapping every row to /r/Synonym, and the exact accept/skip rules
+  per source file.
+- species_reviewed.csv also required cross-referencing a SECOND local
+  checkout, globalwordnet/english-wordnet's `src/yaml/` synset source (the
+  same one corpus/wordnet/generate.mjs reads), to resolve each row's SSID
+  into a representative lemma — that CSV alone carries no lemma text.
+- Conversion tool: corpus/namenet/generate.mjs (tmct code, MPL-2.0).
+
+Share-alike
+-----------
+
+CC-BY-4.0 does NOT require share-alike (unlike ConceptNet's CC-BY-SA 4.0 in
+corpus/conceptnet/) — a CC-BY-4.0 derivative may be relicensed, provided
+attribution is preserved. This repository chooses to keep redistributing
+namenet.jsonl itself under CC-BY-4.0 regardless, to stay unambiguous about
+its origin, subject to the license-status caveat above. The code in this
+directory (generate.mjs) is tmct code under the repository's MPL-2.0; only
+the data file (namenet.jsonl) carries the CC-BY-4.0 label.