polymath-society 0.2.4

package/LICENSE

@@ -0,0 +1,52 @@
+Copyright (c) 2026 Akshay Iyer (Flomi Inc. / Polymath Society). All Rights Reserved.
+
+PROPRIETARY AND CONFIDENTIAL — SOURCE-AVAILABLE, NOT OPEN SOURCE.
+
+This software, in both source and compiled/bundled form, together with its
+structure, rubrics, prompts, methods, and output formats (collectively, the
+"Software"), is the proprietary and confidential property of the copyright
+holder. Publication to the npm registry is for distribution and execution
+convenience only; it does NOT place the Software in the public domain, does NOT
+make it open source, and grants NO rights except the limited license below.
+
+1. LIMITED LICENSE TO RUN. Subject to your continuous compliance with this
+   License, the copyright holder grants you a personal, non-exclusive,
+   non-transferable, non-sublicensable, royalty-free, and REVOCABLE license to
+   download and execute the UNMODIFIED published package, as distributed on npm,
+   on machines you own or control, solely to analyze your own data and view the
+   resulting reports. This is the only right granted.
+
+2. PROHIBITED. Except as expressly permitted in Section 1, and except to the
+   narrow extent a restriction below is unenforceable under applicable law, you
+   may NOT, in whole or in part:
+     - copy, reproduce, host, or store the Software (beyond the transient copies
+       automatically made by npm and Node.js to run it under Section 1);
+     - modify, adapt, translate, or create derivative works of the Software;
+     - redistribute, republish, sublicense, sell, rent, lease, lend, or
+       otherwise make the Software available to any third party;
+     - reverse engineer, decompile, disassemble, deobfuscate, or otherwise
+       attempt to derive the source code, rubrics, prompts, or methods from the
+       distributed bundles;
+     - use the Software, its outputs, its rubrics, its prompts, or its methods
+       to design, train, build, or operate a competing or substantially similar
+       product or service;
+     - remove, obscure, or alter any proprietary or attribution notices.
+
+3. RESERVATION. All rights not expressly granted in Section 1 are reserved by
+   the copyright holder. This License grants no rights in any trademark, and no
+   patent license except as strictly necessary to exercise Section 1.
+
+4. TERMINATION. This License terminates automatically and immediately upon any
+   breach, and may be revoked by the copyright holder at any time. On
+   termination you must cease all use and delete all copies.
+
+5. NO WARRANTY. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO
+   EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+   OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+Any unauthorized use is a violation of applicable copyright and other laws and
+may result in legal action. For any use beyond Section 1, contact the copyright
+holder for written permission.

package/README.md

@@ -0,0 +1,311 @@
+# polymath-society
+
+> **Proprietary — All Rights Reserved (source-available, not open source).** You may run the unmodified npm package to analyze your own data; copying, modifying, redistributing, reverse-engineering the bundles, or using its methods to build a competing product is prohibited. See [LICENSE](./LICENSE).
+
+
+A **local app** for understanding how you work from your own **Claude Code** and
+**Codex** agent logs — parallelism, flow-state, throughput, per-project
+contributions, and (opt-in) AI-graded judgment criteria.
+
+Three things, in one package:
+
+1. **Deterministic metrics** — computed in-process from the JSONL on your disk.
+   Zero LLM, zero network. Facts, not judgments. (Instant and free.)
+2. **Local LLM grading** *(opt-in, `--grade`)* — grades abstraction, taste,
+   delegation, expertise, and frontier tool-use by invoking the **local
+   `claude -p` / `codex` binary you're already logged into**. No API key; it
+   spends your own subscription. Your prompts never leave the machine.
+3. **A local web UI** *(`serve`)* — the same warm "Code tab" view the hosted
+   Polymath app shows, served on a free port, with **per-section Share**.
+
+---
+
+## What it reads
+
+- `~/.claude/projects/**/*.jsonl` — Claude Code sessions
+- `~/.codex/sessions/**/*.jsonl` — Codex sessions
+
+(Override with `CLAUDE_PROJECTS_DIR` / `CODEX_SESSIONS_DIR` env vars.)
+
+It separates **your real interactive sessions** from headless agent runs,
+auth-ping sessions, and machine-assembled mega-prompts (the `klass` /
+`klassReason` on every parsed session is transparent and auditable), de-dupes
+resume/fork copies, and then computes everything below over the canonical set.
+
+## What it computes
+
+| Metric | What it is |
+| --- | --- |
+| **sessions** | per-session structural facts: duration, active time, turns, tool counts, models, tokens, modes, renames |
+| **parallelism** | sweep-line concurrency across sessions — max concurrent, minutes spent at each level, per-day overlap, top windows |
+| **day-chart** | per-day Gantt of every conversation's active spans (clipped to local midnight) |
+| **flow** | every 10-minute slot classified in-flow / active-pause / away (rapid rhythm + dictation beat the gaps) |
+| **throughput** | words you actually *typed* per day (pasted code stripped) → a 1–11 score, plus a proven ceiling |
+| **projects** | GitHub-style per-project days / hours / range |
+| **aggregate** | average throughput over substantial days + flow stats (work window, % in flow, when flow peaks) |
+
+---
+
+## Install
+
+```bash
+npm install polymath-society
+# or run the CLI without installing:
+npx coding-analyzer
+```
+
+## CLI
+
+```bash
+coding-analyzer                 # human-readable summary of the deterministic profile
+coding-analyzer --json          # full profile JSON to stdout
+coding-analyzer --out p.json    # write full profile JSON to a file
+
+coding-analyzer projects        # just the projects/contributions view (JSON)
+coding-analyzer flow            # just the per-day flow slots + totals (JSON)
+coding-analyzer aggregate       # just the corpus aggregate (JSON)
+
+coding-analyzer grade           # OPT-IN: AI-grade your sessions on your OWN
+                                #   Claude Code / Codex login (no API key)
+coding-analyzer serve           # scrape → (optionally --grade) → open the web UI
+coding-analyzer serve --grade   # …including the AI-graded sections
+```
+
+Flags: `--no-codex` · `--idle <min>` · `--tz <IANA>` · `--span <hours>` ·
+`--json` · `--out <file>` · `--grade` · `--adapter <cli|codex>` · `--model <id>` ·
+`--max-sessions <n>` · `--port <n>` · `--share-url <url>` · `--open`
+
+Example summary:
+
+```
+========== DETERMINISTIC CODING PROFILE ==========
+timezone America/Los_Angeles · idle-gap 5m
+sessions: 106 interactive (canonical)  ·  1101 agent/excluded  ·  19 resume-copies dropped
+active work time: 147.5h   tool calls: 16,017   subagents: 41   queue-ahead: 2271
+
+PARALLELISM
+  max concurrent sessions: 6
+
+THROUGHPUT
+  proven ceiling (≥3 days): 10/11
+  AVG over substantial days: 7/11 — 5960 words/day over 30/50 days
+
+FLOW
+  work window: 12:30pm–6:40pm  over 47 active days
+  in flow: 63% of active time  ·  86.5h total (1.8h/day)
+
+PROJECTS
+  4 projects · 37 active days · 102h
+```
+
+## The local app (`serve`)
+
+```bash
+coding-analyzer serve            # deterministic only — instant, free
+coding-analyzer serve --grade    # + AI-graded sections (spends your subscription)
+coding-analyzer serve --grade --open --port 8765
+```
+
+`serve` scrapes `~/.claude/projects` + `~/.codex/sessions`, optionally grades,
+starts a tiny zero-dependency HTTP server on a free port, and prints the
+clickable `http://localhost:<port>` URL. `--grade` writes its analysis to
+`./.data/coding` under the **current directory** — re-run from the same
+directory and it resumes (already-graded sessions are skipped) instead of
+re-grading from scratch. The page reproduces the hosted app's
+**Code tab** — the same warm palette, cards, contributions heatmap, flow stats,
+throughput scatter, and (when graded) the criterion cards with verbatim receipts.
+
+The server exposes:
+
+| Route | What |
+| --- | --- |
+| `GET /` | the bundled static UI |
+| `GET /profile.json` | the computed profile, organized into the share-contract sections |
+| `GET /meta.json` | `{ version, shareUrl }` for the share bar |
+| `POST /share` | proxies the chosen sections to the share endpoint (server-side — no browser CORS) |
+
+### Local LLM grading (no API key)
+
+Grading is **opt-in** because it spends your tokens; the deterministic metrics
+stay instant and free. With `--grade`, the package invokes the **local
+`claude -p` (or `codex`) binary you're already logged into** — billed to your
+Claude / ChatGPT subscription, never an API key. On startup it detects whether a
+backend is installed *and* logged in; if not, it prints the exact fix (e.g. *run
+`claude` to log in*) instead of failing obscurely, and `serve` falls back to
+deterministic-only.
+
+```bash
+coding-analyzer grade                       # grade + write graded.json, print means
+coding-analyzer grade --adapter codex       # pin the Codex backend
+coding-analyzer grade --max-sessions 20     # cap the token/time budget
+```
+
+The five graded criteria — **abstraction, taste, delegation, expertise,
+frontier** — are ported from the main Polymath pipeline (same rubric, 1–11 ladder
+with verbatim quotes, per-conversation ceiling 10). Grading plugs into the
+`analyze()` `gradeProvider` seam (see Library below).
+
+### Share — per-section selection
+
+Every section in the UI has a checkbox; tick the ones you want and hit **Share
+selected** in the footer bar. The browser sends only the ticked keys to the local
+server, which forwards exactly this contract to the share endpoint:
+
+```http
+POST <shareUrl>
+Content-Type: application/json
+
+{
+  "source": "coding-analyzer",
+  "version": "<pkg version>",
+  "name": "<optional user-provided name>",
+  "sharedAt": "<ISO8601>",
+  "sections": { "<key>": <that section's data> }
+}
+```
+
+`key ∈ { howYouWork, snapshot, workstyle, parallelism, lixiThroughput, topDays,
+abstraction, taste, delegation, expertise, frontier, operate }` — only ticked
+keys appear in `sections`. The endpoint defaults to
+`http://localhost:3100/api/coding-share` (dev) and is overridable with
+`--share-url <url>` or `PS_SHARE_URL`. **TODO:** set the production share URL
+before shipping. The local server does the POST server-side, so the browser never
+hits CORS.
+
+### How the bundled UI is produced / rebuilt
+
+The UI sources live in `ui/` (`index.html`, `styles.css`, `app.js` — vanilla JS,
+no React/Tailwind; the warm palette tokens and Card/Chip primitives are
+hand-ported to plain CSS). `npm run build` runs `tsc` then `scripts/build-ui.mjs`,
+which **esbuild**-bundles `ui/app.js` → `dist/ui/app.js` (minified, IIFE, zero
+runtime deps) and copies the HTML/CSS. The server serves `dist/ui/`, which ships
+inside the published package. To rebuild only the UI: `npm run build:ui`.
+
+## Library
+
+```ts
+import { analyze } from "polymath-society";
+
+const profile = await analyze({
+  codex: true,            // include ~/.codex/sessions (default)
+  idleGapMin: 5,          // gap that breaks a session into active intervals
+  tz: "America/Los_Angeles",
+  spanHourMin: 4,         // "substantial day" threshold for the throughput avg
+});
+
+console.log(profile.concurrency.maxConcurrency);
+console.log(profile.throughput.ceiling);          // 1–11, proven on ≥3 days
+console.log(profile.flow.totals.flowFraction);
+console.log(profile.projects.projects);
+```
+
+Every building block is exported too, so you can compose your own pipeline:
+
+```ts
+import {
+  readAllSessions, toSessionRecords, buildConcurrency, buildDayChart,
+  markDuplicates, computeFlow, computeProjects, computeAggregate,
+  proseWords, throughputScore, throughputCeiling,
+} from "polymath-society";
+
+const raw = await readAllSessions();
+const interactive = raw.filter((s) => s.klass === "interactive");
+const records = toSessionRecords(interactive);
+await markDuplicates(records);
+const canon = records.filter((r) => !r.duplicateOf);
+const conc = buildConcurrency(interactive, canon);
+const flow = await computeFlow(canon);
+// …
+```
+
+### Local LLM grading via `analyze()`'s `gradeProvider`
+
+`analyze()` is deterministic by default and never calls a model. The grading
+seam is the optional `gradeProvider`: pass one and `analyze()` attaches a
+`graded` block of per-criterion means. The package ships `LocalGradeProvider`,
+which implements that seam by grading on your **local Claude Code / Codex** CLI:
+
+```ts
+import { analyze, LocalGradeProvider } from "polymath-society";
+
+const provider = new LocalGradeProvider({
+  adapter: "cli",       // or "codex"; omit for auto (first installed + logged-in)
+  model: "sonnet",      // grading model (cli only; codex ignores it)
+  maxSessions: 20,      // cap the token/time budget
+});
+
+const profile = await analyze({ gradeProvider: provider });
+profile.graded;         // { abstraction: { mean, n }, taste: { mean, n }, … }
+provider.detail();      // richer per-criterion distributions + per-session takes (UI)
+```
+
+Or supply your own `gradeProvider` (any object with `criteriaMean(records)`) to
+fold in grades from a different pipeline.
+
+```ts
+const profile = await analyze({
+  gradeProvider: { criteriaMean: () => ({ taste: { mean: 8.2, n: 40 } }) },
+});
+```
+
+### Serving programmatically
+
+```ts
+import { analyze, LocalGradeProvider, buildWebProfile, startServer } from "polymath-society";
+
+const provider = new LocalGradeProvider();
+const profile = await analyze({ gradeProvider: provider });
+const web = buildWebProfile(profile, provider.detail());
+const { url } = await startServer({ profile: web, version: "0.2.0", shareUrl: "https://…/api/coding-share" });
+console.log(url);
+```
+
+## Project aliases
+
+A session's project is its working directory, so the same project shows up under
+several paths (parent-folder runs, old names). Pass `aliases` to canonicalize:
+
+```ts
+await analyze({
+  aliases: [
+    { name: "Polymath", match: ["/polymath-society", "/polymath"], note: "merged old name" },
+  ],
+});
+```
+
+Without aliases, the leaf directory name is used.
+
+## Configuration
+
+| Option (lib) | Flag (CLI) | Env | Default |
+| --- | --- | --- | --- |
+| `codex` | `--no-codex` | | `true` |
+| `idleGapMin` | `--idle` | | `5` |
+| `tz` | `--tz` | `CODING_TZ` | `America/Los_Angeles` |
+| `spanHourMin` | `--span` | | `4` |
+| — | `--port` | | free OS-assigned |
+| — | `--share-url` | `PS_SHARE_URL` | `http://localhost:3100/api/coding-share` |
+| — | `--adapter` | `CODING_ANALYZER_ADAPTER` | auto (`cli` → `codex`) |
+| — | — | `CLAUDE_BIN` / `CODEX_BIN` | resolved from PATH |
+| — | — | `CLAUDE_PROJECTS_DIR` | `~/.claude/projects` |
+| — | — | `CODEX_SESSIONS_DIR` | `~/.codex/sessions` |
+
+## Privacy
+
+On-device by default. The deterministic library reads local files and returns
+plain objects — no telemetry, no network, no model inference.
+
+**Grading** (`--grade`) runs on the **local CLI you're logged into** (`claude -p`
+/ `codex exec`) — your prompts are read from disk and graded on your own
+subscription; nothing is sent to a third party. The **only** outbound network
+call the package ever makes is `POST /share`, and only for the exact sections you
+tick, to the endpoint you configure.
+
+## Requirements
+
+Node.js ≥ 18, ESM only. Grading additionally needs **Claude Code** or **Codex**
+installed and logged in (`claude` / `codex login`).
+
+## License
+
+MIT

package/dist/DATA-MAP.md

@@ -0,0 +1,109 @@
+# DATA-MAP.md — how an agent traverses this person's local record
+
+You are an agent with READ access to the `.data/` directory of a Polymath installation.
+This map tells you what lives where, what the artifacts mean, and how to answer questions
+by going to the source. TRUST THE FILESYSTEM OVER THIS MAP — layouts evolve; `ls`/Glob a
+directory before assuming its contents. Everything is local; nothing you read may be sent
+anywhere, and third parties are referred to by their initials in your replies.
+
+## The two corpora
+
+1. **Life corpus** — the person's imported chat history (ChatGPT, claude.ai), notes
+   (Obsidian, Apple Notes), and the analysis the engine built from them.
+2. **Coding corpus** — their Claude Code / Codex session logs and the deterministic +
+   graded analysis built from those.
+
+When BOTH exist, the strongest answers cross-reference them: a rule declared in the notes
+can be checked against measured coding behavior; a life event can explain a low-output
+week. Prefer cross-corpus receipts when the question allows it.
+
+## Life corpus layout
+
+- `.data/signals/index.jsonl` — one JSON per signal. Fields: `docId`, `date` (ISO,
+  the field is `date`, NOT `ts`), `source` (`chatgpt` | `claude` | `obsidian` |
+  `apple-notes`), `title` (an LLM one-line summary — semantically rich, safe to scan in
+  bulk), `paragraph` (a longer summary), `evidence`, `userChars`, `userMessages`.
+  THIS IS YOUR PRIMARY INDEX for the life corpus: grep it by date range, theme keywords,
+  or source before reading anything heavier. Caveats: notes without dates in their path
+  cluster on their import date (a huge one-day spike is an import artifact, not activity);
+  a title "touching" a theme is an upper bound, not proof of deliberation.
+- `.data/signals/timeline.json` — the same signals arranged as a timeline.
+- `.data/sources/…` — raw imported conversation content (large). Only dip in when a
+  specific conversation matters; quote at most a line or two.
+- `grades/<lens>/_person.json` (under `.data/`, engine output) — the person-level
+  aggregation per lens (ocean, agency, reasoning, growth, interpersonal…): facet scores
+  with reasoning. `grades/<lens>/*.allfacets.json` — per-conversation grades: score or
+  null per facet plus verbatim receipt quotes. A facet with ~0 direct grades while its
+  siblings have many means coverage failed, not that the person lacks the trait.
+- `growth-latest.json` / analysis agents' outputs — growth axes (used-to → now milestone
+  timelines anchored on the person's deliberate moves), drivers, circumstances.
+
+## Coding corpus layout (`.data/coding/`)
+
+- `sessions.json` — every session: title, times, `activeMin`, `durationMin`, `humanTurns`,
+  tool counts, `klass` (only `interactive` sessions are the person; the rest are machine
+  runs), `duplicateOf` (fork copies — skip them or you double-count).
+- `focus.json` — the flow analysis: per-day half-hour cells (`S` in-flow / `N` nudging /
+  `G` away), steering runs, run-end boundaries with the person's next messages, gaps,
+  false starts, semantic `features` (LLM-clustered workstreams with day maps and flow
+  share), and `llm` (causal findings, triggers in/out, priority verdicts, leverage,
+  a personalized CLAUDE.md snippet). Flow definition: typed-message gaps ≤6 min sustained
+  ≥20 min; supervision is "nudging", never flow.
+- `flow.json` — the older, looser engaged-time metric (5-min gap tolerance). The report
+  calls this "engaged time", NOT flow. Do not conflate the two.
+- `day-chart.json` — per day, each conversation's active intervals (timestamps).
+- `grades/*.json` — per-session grades against the coding rubric: per criterion a score
+  on the 1–11 ladder, the keyed instance, why, and verbatim quotes. 6 is strong-normal;
+  10–11 are frontier outliers. Scores across different `rubricVersion` values are not
+  comparable.
+- `aggregate.json` (ability ceilings + `bigPicture` nutshell), `expertise.json` (domain
+  knowledge map), `gap.json` (ranked technique recommendations), `frontier.json`,
+  `delegation-rollup.json`, `projects.json`, `concurrency.json` — each self-describing;
+  read the file before citing it.
+
+## Raw Claude Code session JSONL (only if an artifact can't answer)
+
+`~/.claude/projects/<project>/<sessionId>.jsonl`. If you must read one: only `type:"user"`
+entries are candidate person-text, and you MUST skip `isMeta:true`, injected blocks
+(`<task-notification>`, command wrappers, system reminders), compact-continuation
+summaries, and "[Request interrupted…]" markers; fork copies duplicate whole transcripts
+(dedupe by timestamp+text). Prefer the artifacts — they already did this correctly.
+
+## What the gradations mean
+
+Engine facets and coding criteria use a 1–11 ladder where each rung has concrete
+requirements (the rubric text in your context is the authority). "Top X%" bands come from
+a single calibration source; do not invent percentile mappings. Confidence markers
+("tentative") mean thin evidence, and honesty about that beats a confident guess.
+
+## Traversal recipes
+
+- "How often do I X / when did I last X" → grep `signals/index.jsonl` titles by keyword +
+  date; count by month; report the shape (spans, spikes, gaps) with dates.
+- "Why did I get this score" → the grades file for that criterion/facet: rung, keyed
+  instance, verbatim quote. Name the session/conversation and date.
+- "What was I doing on <date>" → signals index for that date (all sources) +
+  `day-chart.json` + `focus.json` day cells. Coding-log silence usually means selling,
+  deciding, or living, not idleness — say so when the coding record is empty but the
+  life corpus isn't.
+- "Did my habit/rule actually happen" → find declarations in the life corpus, then check
+  the MEASURED coding artifacts (start times, flow, features) for execution. Declared vs
+  measured is the highest-value answer shape this dataset supports.
+- Anything about loops → count recurrences across months in the index; three receipts or
+  it isn't a pattern; one is noise.
+
+## Traversal budget
+
+You have a hard turn limit. Budget 2-4 lookups per question: one Glob/ls to orient (only
+if needed), one or two Greps on an index, one Read of the specific artifact. Then ANSWER.
+If you have not found the receipt after 4 lookups, answer with what you have and say what
+you could not find. Running out of turns mid-traversal means the person gets nothing.
+
+## Answer rules
+
+- Receipts on every claim: dates, counts, short quotes (≤2 lines). Never fabricate a
+  file, score, session, or quote. If a lookup comes up empty, say "insufficient data".
+- Plain speech, at most one number per sentence, verdicts not questions, no em dashes.
+- Patterns, never psychology: describe what the record shows; the person decides meaning.
+- Be honest about instrument limits: logs under-observe a life. Absence in one corpus is
+  not absence in the life; check the other corpus before concluding.