flowviant 0.28.4 → 0.28.6

package/bin/lib/claude.mjs

@@ -138,23 +138,32 @@ docs — comprehensive, precisely structured, richly cross-linked. Detailed and
 thorough beats short: a reader should be able to work in a subsystem after
 reading its chapter.
 
-Fixed spine (numeric prefix = reading order):
-- docs/00-start-here.md — the landing page + MASTER TABLE OF CONTENTS: what the
-  product is (2-3 sentences); how to run it locally (prerequisites, install,
-  required env, dev server, tests); then a linked table of contents of EVERY
-  chapter, each with a one-line description; then 2-3 role-based reading paths
-  (e.g. "New to the backend: read 01, then 12, then 14").
-- docs/01-architecture.md — the system at a glance: a Mermaid diagram (a fenced
-  code block whose language is mermaid) of the major components and how they
-  connect, a component-responsibility table, the primary request/data flows, and
-  a link into the chapter for each component.
-- docs/1N-<chapter>.md — ONE chapter per major subsystem (10, 11, 12 …), your
-  choice of chapters, derived from the vault's hub pages. Cover every significant
-  subsystem.
-- docs/90-decisions.md — notable design decisions, each as context, decision,
-  why, and consequences.
-- docs/91-glossary.md — the project's terms of art, alphabetized, each linking to
-  the chapter or vault page that defines it.
+Organize the chapters into CATEGORY FOLDERS: docs/<NN>-<category>/<MM>-<chapter>.md.
+The folder name (minus its numeric prefix, hyphens → spaces) becomes the sidebar's
+bold GROUP HEADER — exactly like the grouped left nav in Stripe / HuggingFace docs.
+Numeric prefixes on BOTH the folder and the file set reading order.
+
+Fixed spine:
+- docs/00-overview/00-start-here.md — the landing page + MASTER TABLE OF CONTENTS:
+  what the product is (2-3 sentences); how to run it locally (prerequisites,
+  install, required env, dev server, tests); then a linked table of contents of
+  EVERY chapter GROUPED BY CATEGORY, each with a one-line description; then 2-3
+  role-based reading paths (e.g. "New to the backend: read Architecture, then
+  Agent fleet, then Data model").
+- docs/00-overview/01-architecture.md — the system at a glance: a Mermaid diagram
+  (a fenced code block whose language is mermaid) of the major components and how
+  they connect, a component-responsibility table, the primary request/data flows,
+  and a link into the chapter for each component.
+- docs/<NN>-<category>/<MM>-<chapter>.md — the subsystem chapters, sorted into a
+  FEW meaningful categories (aim for 2-5 folders) that mirror the codebase's real
+  divisions — e.g. docs/10-core-runtime/, docs/20-api-and-data/, docs/30-frontend/.
+  Each folder groups the RELATED chapters (a category holding a single chapter is a
+  smell — merge or regroup). One chapter per major subsystem; cover every
+  significant one.
+- docs/90-reference/00-decisions.md — notable design decisions, each as context,
+  decision, why, and consequences.
+- docs/90-reference/01-glossary.md — the project's terms of art, alphabetized, each
+  linking to the chapter or vault page that defines it.
 
 EVERY chapter follows this exact anatomy, in order:
   1. YAML frontmatter listing the real repo files the chapter draws on.
@@ -172,11 +181,12 @@ EVERY chapter follows this exact anatomy, in order:
      functions/types, env/config keys, DB tables/columns — as markdown tables.
   6. A "## Gotchas" section: the traps, edge cases, invariants, and non-obvious
      constraints.
-  7. A "## See also" section: [[wikilinks]] to the deeper vault pages, plus
-     relative links to sibling chapters (e.g. "[Architecture](01-architecture.md)").
+  7. A "## See also" section: [[wikilinks]] to the deeper vault pages, plus links
+     to sibling chapters by BASENAME (e.g. "[Architecture](01-architecture.md)").
 
-Cross-link liberally: [[wikilinks]] point to vault pages; relative "NN-name.md"
-links point to sibling chapters; both are clickable in the reader. Keep every
+Cross-link liberally: [[wikilinks]] point to vault pages; sibling-chapter links by
+BASENAME ("MM-name.md") resolve no matter which category folder the target sits in
+— you needn't spell the folder path. Both are clickable in the reader. Keep every
 claim grounded in code you actually read.
 
 Full-sweep protocol:

package/bin/lib/env-cli.mjs

@@ -20,7 +20,7 @@
 import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
 import { createInterface } from 'node:readline';
-import sodium from 'libsodium-wrappers';
+import sodium from 'libsodium-wrappers-sumo'; // sumo: Argon2 for the recovery KDF (see env.mjs)
 import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
 import { ensureKeypair, myPubB64, fetchBundle } from './env.mjs';
 

package/bin/lib/env.mjs

@@ -39,7 +39,10 @@ import {
 import { execFileSync } from 'node:child_process';
 import { homedir, hostname } from 'node:os';
 import { join, dirname, resolve } from 'node:path';
-import sodium from 'libsodium-wrappers';
+// The SUMO build: the standard `libsodium-wrappers` omits Argon2 (crypto_pwhash),
+// which bootstrapProject() needs to derive the recovery-code key — without it
+// crypto_pwhash_SALTBYTES is undefined and bootstrap throws every poll.
+import sodium from 'libsodium-wrappers-sumo';
 import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
 import { c, info, note, ok, warn } from './ui.mjs';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.28.4",
+  "version": "0.28.6",
   "description": "Run your own Claude Code as headless build agents for Flowviant — on your own credentials. Claims dispatched work, opens PRs, captures review evidence, and routes questions back to you.",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.0",
-    "libsodium-wrappers": "^0.8.4",
+    "libsodium-wrappers-sumo": "^0.8.4",
     "ws": "^8.18.0"
   },
   "keywords": [