dravoice 0.1.2 → 0.1.4

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Dravoice contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-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
-AUTHORS OR COPYRIGHT HOLDERS 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 THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Dravoice contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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
+AUTHORS OR COPYRIGHT HOLDERS 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 THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,37 +1,126 @@
-# Dravoice
-
-Dravoice is a local-first CLI for compiling Markdown, MDX, and plain-text
-writing corpora into reusable voice guidance and deterministic draft review
-notes.
-
-It is not an AI-authorship detector, grammar checker, prose linter, or
-third-party author imitation tool. It helps a writer inspect and reuse their
-own measurable rhythm, register, evidence habits, discourse shape, and
-structure.
-
-## Quick Start
-
-```bash
-npx --package dravoice drav learn --examples ./articles --out ./dravoice-voice
-npx --package dravoice drav inspect --voice ./dravoice-voice
-npx --package dravoice drav prompt --voice ./dravoice-voice --format agents --out AGENTS.md
-npx --package dravoice drav brief --voice ./dravoice-voice --topic "A new article topic" --evidence notes.md --out brief.md
-npx --package dravoice drav revise-plan draft.md --voice ./dravoice-voice
-npx --package dravoice drav review draft.md --voice ./dravoice-voice
-npx --package dravoice drav review draft.md --voice ./dravoice-voice --mode strict --format json
-```
-
-`learn` writes a schemaVersion 2 `profile.json` plus local metadata. `inspect`
-makes the learned feature families visible, `prompt` turns high-confidence
-observations into drafting guidance, `brief` creates an evidence-first article
-plan, `revise-plan` ranks calibrated stylometric revision actions, and `review`
-reports family-level drift.
-
-## Fresh Install Smoke Test
-
-From a packed tarball:
-
-```bash
-npm pack
-npm exec --package ./dravoice-0.1.1.tgz -- drav --help
-```
+# Dravoice
+
+Dravoice is a local-first CLI for compiling Markdown, MDX, and plain-text
+writing corpora into reusable voice guidance and deterministic draft review
+notes.
+
+It is not an AI-authorship detector, grammar checker, prose linter, or
+third-party author imitation tool. It helps a writer inspect and reuse their
+own measurable rhythm, register, evidence habits, discourse shape, and
+structure.
+
+## First Successful Run
+
+Start with your own writing, not a blank prompt. Create an `articles`
+directory in the folder where you want to run Dravoice, then copy in at least
+3 representative long-form Markdown, MDX, or plain-text pieces.
+
+```bash
+mkdir -p articles
+```
+
+Your first folder should look like this:
+
+```text
+your-writing-folder/
+  articles/
+    first-piece.md
+    second-piece.mdx
+    third-piece.txt
+```
+
+`./articles` means "the `articles` directory inside my current terminal
+folder." Five to ten pieces gives Dravoice a stronger profile. If
+`./articles` is missing, interactive `init` can look for common writing folders
+such as `./content`, `./posts`, `./blog`, and `./essays`, then preview the
+files before it learns from them.
+
+If your writing is already somewhere else, point Dravoice at that directory:
+
+```bash
+npx dravoice doctor --examples ~/writing
+npx dravoice init --examples ~/writing
+```
+
+### 1. Check, Initialize, and Inspect
+
+```bash
+npx dravoice doctor
+npx dravoice init
+npx dravoice inspect
+```
+
+Run `doctor` before learning so missing folders, unsupported files, weak
+corpora, duplicate-looking files, and length-imbalanced source sets get clear
+next steps. Inspect the profile before trusting it. If the feature-family
+summaries do not look recognizable, improve the source corpus first.
+
+### 2. Generate Guidance and a Brief
+
+```bash
+npx dravoice prompt --out AGENTS.md
+npx dravoice brief "A new article topic" --evidence notes.md --out brief.md
+```
+
+Use the generated guidance and evidence-first brief to draft from claims you can
+actually support.
+
+### 3. Revise and Review
+
+```bash
+npx dravoice revise-plan draft.md
+npx dravoice review draft.md
+```
+
+`doctor` checks corpus readiness, `init` reads your source pieces, writes a
+local profile in `./dravoice-voice`, and writes `.dravoice.yml` project
+defaults. `inspect` makes the learned feature families visible, `prompt` turns
+high-confidence observations into drafting guidance, `brief` creates an
+evidence-first article plan, `revise-plan` ranks calibrated stylometric
+revision actions, and `review` reports family-level drift with calibration
+confidence.
+
+Run `drav help init` or `drav help review` for command-specific help.
+
+## Advanced Automation
+
+Use strict JSON output when CI or local automation should fail on drift:
+
+```bash
+npx dravoice review draft.md --mode strict --format json
+```
+
+Benchmark commands are for validating Dravoice itself, not for a first writer
+workflow:
+
+```bash
+npx dravoice benchmark prepare --examples ./articles --topic "A new article topic" --out ./bench-run --seed 42
+npx dravoice benchmark prepare-many --examples ./articles --topic "A new article topic" --out ./bench-runs --runs 3 --seed 42
+npx dravoice benchmark score --run ./bench-run --judge ./bench-run/judge/judgment.json
+```
+
+Benchmark reports include deterministic margins and repeat-run cautions. A
+single run is directional evidence only. Score output includes suggested
+follow-up seeds for repeated validation runs.
+
+## Trust Boundaries
+
+Dravoice profiles include per-family calibration diagnostics: threshold
+observations, stability, minimum-evidence checks, and whether a family is usable
+for findings. Weak corpora produce cautious guidance. Strict review can surface
+document-level discourse, lexical, register, and structure drift, but the
+findings remain revision guidance, not authorship proof.
+
+V2 profiles expose marker-set register metadata, mixed-register warnings,
+heading-depth and section-order structure signals, paragraph-localized
+revision actions, expanded MDX scaffold filtering before analysis, and
+library-level custom register marker sets for project-specific scoring.
+
+## Fresh Install Smoke Test
+
+From a packed tarball:
+
+```bash
+npm pack --json
+node -e "const { execFileSync } = require('node:child_process'); const pack = require('./package.json'); const tarball = './' + pack.name + '-' + pack.version + '.tgz'; execFileSync('npm', ['exec', '--package', tarball, '--', 'drav', '--help'], { stdio: 'inherit' });"
+```

package/bin/dravoice.js

@@ -1,10 +1,11 @@
-#!/usr/bin/env node
-import { runCli } from "../src/index.js";
-
-const code = await runCli(process.argv.slice(2), {
-  cwd: process.cwd(),
-  stdout: process.stdout,
-  stderr: process.stderr,
-});
-
-process.exitCode = code;
+#!/usr/bin/env node
+import { runCli } from "../src/index.js";
+
+const code = await runCli(process.argv.slice(2), {
+  cwd: process.cwd(),
+  stdin: process.stdin,
+  stdout: process.stdout,
+  stderr: process.stderr,
+});
+
+process.exitCode = code;

package/package.json

@@ -1,45 +1,47 @@
-{
-  "name": "dravoice",
-  "version": "0.1.2",
-  "description": "Compile article voice profiles into reusable LLM writing context, evidence-first briefs, and deterministic draft review notes.",
-  "type": "module",
-  "bin": {
-    "drav": "bin/dravoice.js"
-  },
-  "exports": {
-    ".": "./src/index.js"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "lint": "node ../../scripts/check-js-syntax.js packages/js-cli",
-    "test": "node --test test/v2.test.js"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "voice",
-    "writing",
-    "cli",
-    "llm",
-    "markdown"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/hilmimuktitama/dravoice.git",
-    "directory": "packages/js-cli"
-  },
-  "bugs": {
-    "url": "https://github.com/hilmimuktitama/dravoice/issues"
-  },
-  "homepage": "https://github.com/hilmimuktitama/dravoice#readme",
-  "publishConfig": {
-    "access": "public"
-  },
-  "license": "MIT"
-}
+{
+  "name": "dravoice",
+  "version": "0.1.4",
+  "description": "Compile article voice profiles into reusable LLM writing context, evidence-first briefs, and deterministic draft review notes.",
+  "type": "module",
+  "bin": {
+    "dravoice": "bin/dravoice.js",
+    "drav": "bin/dravoice.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "lint": "node ../../scripts/check-js-syntax.js bin src test",
+    "test": "node --test test/v2.test.js",
+    "prepublishOnly": "npm run lint && npm run test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "voice",
+    "writing",
+    "cli",
+    "llm",
+    "markdown"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hilmimuktitama/dravoice.git",
+    "directory": "packages/js-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/hilmimuktitama/dravoice/issues"
+  },
+  "homepage": "https://github.com/hilmimuktitama/dravoice#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}