naive-framework 0.3.0 → 0.4.0

package/interface/cli/naive.mjs

@@ -17,7 +17,7 @@
 //   naive typegen                                   write .naive/types/ from the route table and the MCP tools
 //   naive upgrade [<venture dir>] [--framework]     move a venture onto the next Naive layout; --framework first
 //                                                   updates the installed framework with the venture's package manager (I-29)
-//   naive port <folder> --venture <dir> [--to <path>]  plan moving a folder into the venture as it is (repo/<name>)
+//   naive port <folder> --venture <dir> [--to <path>]  plan moving a folder into the venture as it is (codebase/<name>)
 //   naive port --venture <dir> --apply --confirm port
 //                                                   carry out that plan (EE-076)
 //   naive migrate --from <project> --venture <dir>  an agent rewrites the project as Naive records, as a plan and decisions

package/interface/layer.json

@@ -10,6 +10,10 @@
     {
       "id": "naive-setup",
       "path": "interface/skills/naive-setup/SKILL.md"
+    },
+    {
+      "id": "choosing-artifacts",
+      "path": "interface/skills/choosing-artifacts/SKILL.md"
     }
   ],
   "records": [

package/interface/skills/choosing-artifacts/SKILL.md

@@ -0,0 +1,113 @@
+---
+type: knowledge
+tags: [everything-ecosystem, naive, skills, interface, artifacts, records, views]
+ai-model: claude-opus-5.5
+created: 2026-10-29T20:12:08Z
+source: hybrid
+name: choosing-artifacts
+description: >
+  Decide whether a venture action should build an artifact (a rendered view a
+  person reads, presents, shares or fills in) and which kind, and keep records,
+  the source of truth in k-base/, separate from artifacts, which are views built
+  from records and cite them. General for any agent, with a section for Claude's
+  own artifacts in Claude Code and claude.ai.
+  MANDATORY TRIGGERS: make an artifact, build a page, make a deck, make a
+  dashboard, pitch deck, investor update, show me, visualize, one-pager, which
+  artifact, should this be a doc, render this record.
+---
+
+# Choosing artifacts
+
+Interface layer. An artifact is a rendered view; a record is the source of truth. Build an artifact from records when a person needs to look at, present, share or fill in something. Never let the artifact become the record.
+
+## The core rule: records are not artifacts
+
+- A **record** is a file in the venture's `k-base/` with a schema. It is what agents read, what decisions cite and what `naive check` tests.
+- An **artifact** is a page, deck, dashboard or file made from one or more records for a reader. A marketing site describes the company, but the company's facts live in its records, not on the site.
+- Every artifact names the records it was built from (route and revision or date), so a reader can trace each claim.
+- When a record changes, rebuild the artifact. Never hand-edit an artifact to change a fact.
+- What people type into an artifact (a form, a docket, comments) is input. Write it back through the router as a proposal or a draft in `_drafts/`; a person settles it. The artifact's own stored state is never the source of truth.
+- Outside a Naive venture the same rule holds: name what the view was made from, and keep the facts where they already live.
+
+## Should this be an artifact at all?
+
+Answer in the conversation when the result is short, read once and acted on now. Build an artifact when any of these is true:
+
+1. Someone other than the requester will read or use it.
+2. It will be presented, printed, exported or sent.
+3. A person needs to fill it in, decide on it or come back to it.
+4. It is longer than about fifteen lines, or a picture explains it better than prose.
+
+If it belongs in the venture's code (a README, a spec that ships, code docs), write a file in `codebase/` instead.
+
+## Kinds of artifact
+
+| Kind | Use it for |
+|---|---|
+| Document | Writing people keep editing or pass around: memo, plan, spec, brief, report, notes |
+| Deck | Something to present or page through: pitch, investor update, demo-day talk |
+| Dashboard | Numbers people read: KPIs, runway, scorecards. Every number shows its source record |
+| Design | Visual work: landing pages, screens, mockups, ads, social posts |
+| Design system | The brand's tokens, type, components and assets, built from the brand record |
+| Page | Explainers, diagrams, interactive tools, trackers, forms |
+| File | Only when a format is named (.pptx, .docx, .xlsx, PDF) or an existing file is to be changed |
+
+## Decide in order
+
+1. Is it an artifact at all? (above)
+2. Did the person name a format? Use it.
+3. Writing to edit: document. To present: deck. Data to read: dashboard. A visual: design. A brand: design system.
+4. Otherwise a page. Add a diagram, charts or interactivity only when each earns its place.
+5. List the records it reads, and put that source list in the artifact.
+6. Read the records through Naive (`mentura_read`, or `naive` routes), never from memory. A record that is missing, a draft or stale is shown as such, never filled in.
+
+## Actions and their artifacts
+
+Each function's skills say which of its actions build which artifact. This is the starting map; it is a proposal until the founder confirms it in `naive.config.json` or the function's own skill.
+
+| Function | Action | Artifact | Built from |
+|---|---|---|---|
+| Foundation | Review the strategic foundation | Document (brief) | foundation/problem, foundation/icp, telos, the phase in venture.json |
+| Foundation | Decide pending decisions | Page that collects answers (the docket) | decisions/; answers go back as decisions a person settles |
+| Validation | Plan or report an experiment | Document | validation records and evidence/ |
+| Validation | Track evidence over time | Dashboard | evidence/ and metric records |
+| Validation | Run interviews | Page that collects answers (intake form) | the interview schema; answers become records |
+| Marketing | Draft a landing page or ad | Design | positioning and marketing/brand |
+| Marketing | Set up the brand | Design system | marketing/brand |
+| Marketing | Plan content | Document | positioning and calendar records |
+| Product | Write a spec or roadmap | Document | product/ and decisions/ |
+| Product | Show a flow or architecture | Page with a diagram | product/ |
+| Product | Prototype a screen | Design | product specs |
+| Money | Show runway, burn, revenue | Dashboard | money/ (from the bank or accounting source in sources.json) |
+| Money | Build a model or budget | File (.xlsx) when asked, else dashboard | money/ and finance/ |
+| Investors | Pitch or investor update | Deck | foundation/, evidence/ (traction) and money/ |
+| Any | Release notes for a release | Document | the release in meta/releases/ |
+
+## Checks before you publish
+
+- [ ] The artifact names its source records.
+- [ ] No fact appears that is missing from a record. If one is needed, write the record first (as a draft) or mark the claim as a proposal.
+- [ ] Agent-drafted content is marked as a proposal, never as the founder's words.
+- [ ] Input the artifact collects has a path back to records.
+- [ ] Nothing from `_private/`, no secrets, keys or `.env` contents.
+- [ ] Nothing imitates a real person or organization.
+
+## In Claude (Claude Code and claude.ai)
+
+Claude publishes artifacts with its `Artifact` tool. The kinds above map onto the artifact types on the person's account, which change, so always start a new artifact with `Artifact` `action: "quickstart"` and the fitting `intent`; it names the type to start from and the default design system.
+
+| Kind | Claude artifact type | Intent |
+|---|---|---|
+| Document | Docs (through the Claude Docs connector) | `document` |
+| Deck | Slides | `slides` |
+| Dashboard | Dashboard | `other` |
+| Design | Design | `design` |
+| Design system | Design System | `other` |
+| Page | plain HTML page, after loading `artifact-design` | `other` |
+| File | the matching file skill (docx, pptx, xlsx, pdf) | none |
+
+- **Diagram:** load `artifact-diagramming` when a picture shows the real mechanism.
+- **Charts:** load `dataviz` before drawing any chart; prefer the Dashboard type when the page is mostly data.
+- **Collecting input:** load `artifact-capabilities` and declare the smallest set: `db` and `user` for answers from several people (the docket, an intake form), `artifact` for a page that saves its own versions. Sync what it holds back to records through Naive; never treat the page's store as the record.
+- **Updating:** republish to the same URL when the records change, so the link people hold stays current.
+- Publish privately and give the link. Sharing it further is the founder's call.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naive-framework",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Naive, a venture development framework: conventions, routes, records, checks and an agent interface for building a venture.",
   "type": "module",
   "license": "MIT",

package/schema/check-data-packages.mjs

@@ -36,7 +36,7 @@ for (const v of walk(dir)) {
     const base = ventureFile(v, pack);
     if (!existsSync(base)) continue;
     for (const name of readdirSync(base)) {
-      if (name.startsWith("_") || name.startsWith(".")) continue;
+      if (name.startsWith("_") || name.startsWith(".") || name === "README.md" || name === "AGENTS.md") continue;
       const p = join(base, name);
       if (!statSync(p).isFile() || !name.endsWith(".json")) errors.push(`${id}/${pack}/${name}: a master record is <id>.json`);
     }

package/schema/init-venture.mjs

@@ -19,7 +19,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
-import { ventureFile } from "./venture-paths.mjs";
+import { KBASE, ventureFile } from "./venture-paths.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const repo = join(here, "..");
@@ -50,13 +50,13 @@ Object.assign(venture, { owner: "self", status: "active", profile: structured ?
 // The package folders (EE-070); a typed venture gets its type's packages.
 const packageDirs = vtype ? vtype.packages : ["foundation", "validation", "product", "marketing", "finance", "people", "customers", "investors", "money"];
 if (structured) {
-  // venture.json first, so every path below resolves into knowledge/ and meta/. The org chart starts flat:
+  // venture.json first, so every path below resolves into k-base/ and meta/. The org chart starts flat:
   // one function per package, owned by no one until create-venture or the founder names the owner.
   venture.layout = "structured";
   venture.functions = Object.fromEntries(packageDirs.map((p) => [p, { owner: null }]));
-  for (const layer of ALL) venture.layers[layer] = on.includes(layer) ? { location: "knowledge/" } : false;
+  for (const layer of ALL) venture.layers[layer] = on.includes(layer) ? { location: `${KBASE}/` } : false;
   writeFileSync(join(dir, "venture.json"), JSON.stringify(venture, null, 2) + "\n");
-  for (const sub of ["knowledge", "meta"]) mkdirSync(ventureFile(dir, sub), { recursive: true });
+  for (const sub of [KBASE, "meta"]) mkdirSync(join(dir, sub), { recursive: true });
 }
 for (const layer of structured ? [] : ALL) {
   if (!on.includes(layer)) { if (only !== null || !["governance", "interface"].includes(layer)) venture.layers[layer] = false; continue; }
@@ -70,6 +70,16 @@ if (!structured) for (const sub of ["products", "accounts"]) { mkdirSync(venture
 for (const sub of ["raw/dump", "raw/sources", "ideas", ...packageDirs, "decisions", "evidence", ...(structured ? [] : ["public"]), "_private", "_drafts", ".release"]) {
   mkdirSync(ventureFile(dir, sub), { recursive: true });
 }
+// Every package folder explains itself (EE-086): a README.md from its package, for people. GitHub and
+// editors show it when the folder is opened; an AGENTS.md beside it is the founder's, for agents.
+if (structured) for (const pkg of packageDirs) {
+  const f = join(repo, "packages", pkg, "package.json");
+  if (!existsSync(f)) continue;
+  const p = JSON.parse(readFileSync(f, "utf8"));
+  const lines = [`# ${p.title ?? pkg}`, "", p.purpose ?? "", ...(p.required?.length ? ["", `What goes in it first: ${p.required.join(", ")}.`] : []), ...(p.optional?.length ? [`Also: ${p.optional.join(", ")}.`] : []),
+    ...(p.gates?.length ? ["", `It is ready when ${p.gates.join("; ")}.`] : []), "", `Owner: whoever owns the ${pkg} function in venture.json.`, ""];
+  writeFileSync(join(ventureFile(dir, pkg), "README.md"), lines.join("\n"));
+}
 if (!structured) mkdirSync(join(ventureFile(dir, "pillars")), { recursive: true });
 for (const [name, what] of Object.entries(structured ? {} : pillars.stubs)) {
   const guide = relative(join(ventureFile(dir, "pillars")), join(repo, pillars.guides, `${name}.md`));

package/schema/port-venture.mjs

@@ -7,7 +7,7 @@
 //
 //   node schema/port-venture.mjs <folder> --venture <dir> [--to <path>] [--links <dir> ...]
 //        adds the move to the plan at <venture>/.release/port-plan.json and prints it; moves nothing.
-//        The folder goes to <venture>/repo/<its name> unless --to says where (relative to the venture
+//        The folder goes to <venture>/codebase/<its name> unless --to says where (relative to the venture
 //        or absolute). Run once per folder: each run adds or replaces that folder's item.
 //   node schema/port-venture.mjs --venture <dir> --apply --confirm port [--even-if-busy]
 //        carries out every planned move the founder left as move; any item can be set to leave first
@@ -24,7 +24,7 @@ import { createHash } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { agentFromEnv, record } from "../interface/provenance.mjs";
-import { ventureFile } from "./venture-paths.mjs";
+import { CODEBASE, ventureFile } from "./venture-paths.mjs";
 
 export const PLAN = ".release/port-plan.json";
 export const TRACE = ".release/port-trace.json";
@@ -112,7 +112,7 @@ export function planOne(folder, dir, { to, links = [] } = {}) {
   const src = real(folder);
   const v = real(dir);
   if (inside(v, src)) throw new Error("the venture cannot sit inside the folder it ports");
-  const dest = resolve(v, to ?? join("repo", basename(src)));
+  const dest = resolve(v, to ?? join(CODEBASE, basename(src)));
   const s = statSync(src);
   const item = { action: "move", from: src, to: dest, source: slug(basename(src)), identity: { dev: s.dev, ino: s.ino }, ...measure(src) };
   const warnings = [];

package/schema/venture-paths.mjs

@@ -6,8 +6,11 @@
 //   structured (venture.json layout: "structured"):
 //     venture.json, AGENTS.md, README.md, package.json   at the top (profile.md is README.md)
 //     provenance.jsonl, sources.json, naive.config.json   in meta/; .release/ is meta/releases/
-//     every package (foundation/, people/, _drafts/ ...)  in knowledge/, or in knowledge/(group)/ when the
+//     every package (foundation/, people/, _drafts/ ...)  in k-base/, or in k-base/(group)/ when the
 //                                                         founder mirrors a function as a folder
+//     code the venture keeps (a marketing site, a ported repository)  in codebase/
+//   A structured venture made by 0.3.0 has knowledge/ where k-base/ now is; it is read where it is
+//   until naive upgrade renames it.
 //
 // `logical` goes the other way, for code that walks the disk and matches files against the data model.
 
@@ -17,6 +20,13 @@ import { join, relative, sep } from "node:path";
 const TOP = new Set(["venture.json", "AGENTS.md", "README.md", "package.json", "package-lock.json", ".gitignore"]);
 const META = { "provenance.jsonl": "meta/provenance.jsonl", "knowledge/sources.json": "meta/sources.json", "sources.json": "meta/sources.json", "naive.config.json": "meta/naive.config.json" };
 const cache = new Map();
+export const KBASE = "k-base";
+export const CODEBASE = "codebase";
+
+/** The venture's knowledge-base folder: k-base/, or knowledge/ in a structured venture made before it was renamed. */
+export function kbaseOf(dir) {
+  return !existsSync(join(dir, KBASE)) && existsSync(join(dir, "knowledge", "foundation")) ? "knowledge" : KBASE;
+}
 
 /** The venture's layout: "structured" (EE-086) or "flat". Read once per venture.json change. */
 export function layoutOf(dir) {
@@ -33,7 +43,7 @@ export function layoutOf(dir) {
 
 // The (group)/ folder a package sits in, when the founder mirrors functions on disk.
 function groupOf(dir, pkg) {
-  const kb = join(dir, "knowledge");
+  const kb = join(dir, kbaseOf(dir));
   if (!pkg || existsSync(join(kb, pkg)) || !existsSync(kb)) return null;
   for (const g of readdirSync(kb)) if (/^\(.+\)$/.test(g) && existsSync(join(kb, g, pkg))) return g;
   return null;
@@ -48,10 +58,11 @@ export function physical(dir, rel) {
   if (META[r]) return META[r];
   if (r === ".release" || r.startsWith(".release/")) return "meta/releases" + r.slice(".release".length);
   if (r.startsWith(".naive/") || r === ".naive" || r.startsWith("node_modules") || r.startsWith(".git")) return r;
-  if (r.startsWith("knowledge/") || r.startsWith("meta/") || r.startsWith("repo/")) return r;
+  const kb = kbaseOf(dir);
+  if (r.startsWith(`${kb}/`) || r === kb || r.startsWith("meta/") || r.startsWith(`${CODEBASE}/`) || r.startsWith("repo/")) return r;
   const pkg = r.split("/")[0];
   const g = groupOf(dir, pkg);
-  return `knowledge/${g ? `${g}/` : ""}${r}`;
+  return `${kb}/${g ? `${g}/` : ""}${r}`;
 }
 
 /** The absolute path of a logical path in a venture. */
@@ -64,7 +75,8 @@ export function logical(dir, rel) {
   if (r === "README.md") return "profile.md";
   for (const [l, p] of Object.entries(META)) if (r === p) return l === "sources.json" ? "knowledge/sources.json" : l;
   if (r === "meta/releases" || r.startsWith("meta/releases/")) return ".release" + r.slice("meta/releases".length);
-  if (r.startsWith("knowledge/")) return r.slice("knowledge/".length).replace(/^\([^/]+\)\//, "");
+  const kb = kbaseOf(dir);
+  if (r.startsWith(`${kb}/`)) return r.slice(kb.length + 1).replace(/^\([^/]+\)\//, "");
   return r;
 }