docs: reproducible first canonical M4 economic run for new readers

Open
  • Is something wrong?
#963 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
74/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
node.js, typescript
Domain
developer-experience, documentation

Research direction

Read README.md, package.json, src/index.ts, src/simulation/index.ts, and src/diagnostics/m4Preview.ts; begin by tracing createM4PreviewWorld() and generateM4Preview() and the existing contract in src/diagnostics/m4Preview.test.ts. Add a documented command that runs the canonical TypeScript scenario and prints its deterministic result, then guard the output contract in a test. Done means the README gives one reproducible command, seed, tick count, units, representative verified output, and an accurate description of Pages as a static viewer.

Written by the indexing model from the issue text.

Description

area:docs priority:normal type:docs

Goal

Give a technically curious visitor a verified, reproducible first economic run of the existing canonical TypeScript engine (currently publicly released through M4), not just npm test or a static Pages preview. This is a narrowly scoped onboarding/organic adoption improvement, not a new simulation milestone.

Evidence (read-only, 2026-11-05; master bb16a71bfa07ca818ca60ed61ce0210bbb3df0cf)

  • README explains economics and shows npm ci; npm run typecheck; npm test; npm run build, but no command that runs one scenario and prints an intelligible economic result.
  • package.json still describes the package as “Scaffolding only until REQ-MIGRATION-003”; src/index.ts only exports toolchainStatus(), while the economic API is available via src/simulation/index.ts.
  • A concrete, existing non-vacuous entry point is createM4PreviewWorld() + generateM4Preview(world) in src/diagnostics/m4Preview.ts. The repository already tests the canonical generator and checks the exported artifact byte-for-byte in m4Preview.test.ts.
  • The M4 fixture uses a deterministic seed 42, 60 ticks and samples every 5 ticks, and exposes output, paid wages, household purchases, capital formed, and per-tick employment/needs coverage; this is a plausible example surface, not an independently executed demo in this report.
  • Existing #792 covers licensing/contribution paths (closed); #863 covers static Pages UX; #745 is final M12 release docs and gated on M11. None provides a verified run a canonical scenario now tutorial. Searched issue titles for quickstart, first-run, runnable example and README.

Scope

  1. Add one small checked-in example (or a documented existing canonical command) that a newcomer can run on Node >=22 after npm ci to execute a real deterministic scenario and print a compact, human-readable result with units and an explicit seed/tick count.
  2. Prefer reuse of createM4PreviewWorld / generateM4Preview or another already validated canonical runner. No parallel economic implementation, no fabricated synthetic outputs.
  3. Add an exact README “Run your first simulation” block with expected representative results recorded from a real clean-clone run, or deterministic assertions if numeric values vary by version. Say explicitly that Pages is a static saved-run viewer and this CLI/example executes the TypeScript engine.
  4. Correct the visibly stale package.json description and src/index.ts scaffolding commentary only if their intended audience/API responsibilities are confirmed; retain private: true. Document supported imports rather than silently changing package exports.
  5. Keep existing M11 observatory / M12 cleanup scope independent.

Non-goals

No economic rule, scenario seed, physical-stock or money-creation logic changes; no production browser observatory, packaging/npm publish, GitHub Pages deployment, licensing or workflow-policy changes; do not hand-edit machine-owned spec mirrors. No claim that the current Pages deployment was browser-tested by this finding.

Acceptance criteria

  • A new reader can copy one documented command after setup to get actual canonical TypeScript simulation output (not only a test pass or playback of committed JSON).
  • Scenario/seed/ticks/units and output provenance are explicit; two independent identical runs return the same deterministic result.
  • Test guards the command and its documented output contract, using canonical source; errors explain missing prerequisites.
  • README, package metadata and public statement about the static Pages viewer remain internally consistent.
  • Separate judge/CI verifies documentation and example on the actual proposed head under AGENTS.md gates.

Verification

Run on a fresh clone with Node >=22: npm ci, the new documented quickstart command twice and compare outputs, npm run typecheck, npm test, npm run build; include exact commands and output in the PR. Not run by Starry: her connected source read succeeded but this environment cannot fetch a fresh dependency tree/repository clone.

Dominant language
TypeScript
Stars
4
Forks
0
Avg merge
6h 26m
Merged PRs (30d)
168

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from drevendev/trade_simulation

All issues in drevendev/trade_simulation

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.