Document the first quant-research artifact

.github/ISSUE_TEMPLATE/first-use.md

@@ -0,0 +1,34 @@
+---
+name: First-use feedback
+about: Report what happened when you tried a research artifact workflow
+title: "[first-use] "
+---
+
+Please omit participant data, credentials, and unpublished instruments.
+
+## Version and context
+
+- package/tag:
+- Node.js:
+- research domain at a non-sensitive level:
+
+## First-use result
+
+- [ ] produced a codebook
+- [ ] produced a recode artifact
+- [ ] produced a coverage result
+- [ ] produced analysis syntax
+- [ ] did not reach a first result
+
+Time to first result:
+
+## Task and friction
+
+What input fixture or instrument shape did you use? What happened, what did
+you expect, and what should change?
+
+## Evidence
+
+- command:
+- output or error code:
+- safe redacted excerpt:

README.md

@@ -1,12 +1,12 @@
 # @agentbiz/quant-research
 
-Deterministic **instrument, coverage, recode, and measurement-spec** contracts for agentic quantitative research.
+`@agentbiz/quant-research` turns a declared research instrument into a checked codebook, recode artifact, coverage result, and analysis specification before anyone opens SPSS, AMOS, SmartPLS, or lavaan.
 
 Large language models do not reliably keep Likert bounds, reverse-keyed items, construct codes, or SEM path lists consistent. This library is the typed contract those agents should call **before** anyone opens SPSS, AMOS, SmartPLS, or lavaan.
 
 It compiles JSON in and emits dictionaries, coverage maps, recode artifacts, SPSS syntax, lavaan specs, AMOS path lists, and SmartPLS indicator maps. It does **not** estimate models, compute fit indices, write Excel or Google Sheets, or call a model provider.
 
-**Status:** public alpha (`0.1.0-alpha.5`). This release is a deterministic contract and emitter library. It does not estimate SEM, compute fit indices, write Excel or Google Sheets, call a model provider, or claim adoption, downloads, or dependent repositories.
+**Live status (2026-08-24):** public alpha (`0.1.0-alpha.5` on GitHub, 0 stars, 0 forks). No external user, downstream repository, or pilot is verified. npm `alpha` resolves `0.1.0-alpha.5` while `latest` remains `0.1.0-alpha.4`. This release is a deterministic contract and emitter library. It does not estimate SEM, compute fit indices, write Excel or Google Sheets, call a model provider, or claim adoption, downloads, or dependent repositories.
 
 > If it caught one inconsistent recode before analysis,
 > [star it](https://github.com/daichunghy/quant-research/stargazers). That is
@@ -40,6 +40,8 @@ This is Github 4. It is not PatchGate, contribkit, or OpenSheet-AI. See [docs/BO
 For citation and clean-room reproduction, see [`CITATION.cff`](CITATION.cff) and
 [`docs/REPRODUCIBILITY.md`](docs/REPRODUCIBILITY.md).
 
+The shortest route to a concrete artifact is the [first-use walkthrough](docs/first-use.md).
+
 ## Install (local)
 
 ```bash

docs/first-use.md

@@ -0,0 +1,33 @@
+# First use: produce one research artifact
+
+The first useful result is not a fitted model. It is a checked research bundle
+that makes the instrument, recodes, coverage, and analysis syntax explicit
+before data analysis begins.
+
+## Ten-minute local path
+
+```bash
+npm ci
+npm run first-use
+```
+
+The outputs should make the following visible:
+
+- construct and item codes with Likert bounds and reverse flags;
+- new recode columns without deleting cases or items;
+- covered, partial, missing, mismatch, and unexpected indicators;
+- declared syntax for lavaan or SPSS without pretending that estimation ran.
+
+The TAM items are demonstrations, not published scales. This package does not
+estimate SEM, compute fit indices, write spreadsheets, call a model provider,
+or decide whether a measurement model is valid.
+
+## What to report
+
+Record the package/tag, study context at a non-sensitive level, time to the
+first useful artifact, first confusing output, and whether a researcher would
+use the result in a real workflow. Use the [first-use feedback form](https://github.com/daichunghy/quant-research/issues/new?template=first-use.md)
+without attaching participant data, credentials, or unpublished instruments.
+
+This path proves deterministic local output. It does not prove external users,
+ethical approval, statistical validity, or package adoption.

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentbiz/quant-research",
   "version": "0.1.0-alpha.5",
-  "description": "Deterministic instrument, recode, and measurement-spec contracts for agentic quantitative research. Does not run SEM or write spreadsheets.",
+  "description": "Builds checked research instruments, recodes, coverage reports, and analysis specs from typed inputs.",
   "license": "Apache-2.0",
   "private": false,
   "repository": {
@@ -46,6 +46,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "first-use": "npm run build && node scripts/first-use.mjs",
     "prepack": "npm run build",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",

scripts/first-use.mjs

@@ -0,0 +1,25 @@
+import { spawnSync } from "node:child_process";
+
+const commands = [
+  ["compile instrument", ["dist/cli.js", "compile", "examples/tam-instrument.json"]],
+  ["emit codebook", ["dist/cli.js", "codebook", "examples/tam-instrument.json"]],
+  ["recode dataset", ["dist/cli.js", "recode", "examples/tam-instrument.json", "examples/tam-dataset.json"]],
+  ["check coverage", ["dist/cli.js", "gap", "examples/tam-instrument.json", "examples/tam-observed.json"]],
+  ["emit lavaan", ["dist/cli.js", "emit-lavaan", "examples/tam-bundle.json"]],
+  ["emit SPSS", ["dist/cli.js", "emit-spss", "examples/tam-bundle.json"]],
+];
+
+for (const [label, args] of commands) {
+  console.log(`\n== ${label} ==`);
+  const result = spawnSync(process.execPath, args, { stdio: "inherit" });
+  if (result.error) {
+    console.error(`${label} failed to start: ${result.error.message}`);
+    process.exit(1);
+  }
+  if (result.status !== 0) {
+    console.error(`${label} exited with status ${result.status ?? 1}`);
+    process.exit(result.status ?? 1);
+  }
+}
+
+console.log("\nfirst-use path passed: deterministic research artifacts were emitted from the demonstration fixtures");