Skip to content

README.md

Latest commit

 

History

History
244 lines (227 loc) · 18.2 KB

README.md

File metadata and controls

244 lines (227 loc) · 18.2 KB
Raw

Numinous Docs Index

The map of the blueprint. Use the reading paths to find your way in, and the single-source-of-truth map to keep things tidy: every topic has one home doc that owns it; every other doc links to that home rather than restating it. If you find yourself duplicating a concept, stop and link instead.

Status: 0.4.0-alpha.16. The 0.1 Public Foundation, 0.2 Flagship Proof, and 0.3 Tactile Alpha agent-and-machine exits are met. Understanding Alpha is the active line, and its 0.4 exit remains open. The headless core, CLI, MCP server, windowed App, GPU and audio adapters, 355 catalog rooms plus hidden content, 6 sims, 11+ games, Journey, standard-controller input, Studio, and a built-in 42-track radio are built.

The MCP face exposes 40 bounded tools over the current and two retained legacy protocol revisions. The consented Watch Agent viewer reconstructs allowlisted room, Studio, and game actions in the App with a bounded in-memory timeline and no persisted transcript. A portable Agent Plugins v1 package supplies host discovery and play-first guidance. The opt-in experience journal persists across clean MCP processes and supports inspection, immutable correction, native or Open Knowledge Format v0.2 export, and confirmed erase. The process-local workspace can deliberately retrieve up to four current exact-subject entries for one named room, explain their sources, and abstain when evidence is absent. The safe room doorway can signal that exact local evidence exists without opening its text or changing the workspace. Three private creation tools return portable titled, signed, and forkable Studio capsules with exact previews and lineage, without host filesystem access.

Critical path now: preserve the completed seven-room Universal Wager and the completed caller-paced Show for minds, close the remaining structural Polish Wave debts, then finish the disabled Sensory Lift App path's physical Windows, macOS, and Linux pacing set before promotion. Its portable runtime correctness probe now runs in the existing three-OS CI matrix without treating CI timing as physical evidence. Shared Studio requests, the typed room catalog, the typed Gauntlet, and local-state path resolution now have one core owner. CLI and MCP local-state adapters are focused modules extracted from their god-files, and MCP discovery plus its immutable tool schema and player-owned journal projections now have dedicated face-local modules. CLI accessibility switch interpretation and terminal reporting now have the same focused ownership. Bounded CLI render dimensions, static hand points, pointer gestures, and interaction-aware status now share a focused render-input adapter. MCP JSON hand points, gestures, canonical echo, and interaction projection now have the corresponding focused adapter. Bounded newline framing, overflow resynchronization, and one-line response writes now share a focused MCP transport adapter. Simulation discovery, lever validation, and result projection share a focused MCP simulation-tool adapter while the simulation rules remain in core. Formula Jam discovery, portable creation projection, optional audio, and encounter receipts now share a focused MCP Studio-tool adapter. Stateless game replay, structured game results, and the shared score table now share a focused MCP game-tool adapter while game rules and persistence remain in core. CLI terminal game presentation, input loops, Journey events, and score posting now share a focused game runtime adapter while seeded rules, deals, legality, and grading remain in core. App game entry, keyboard handling, score posting, and transient feedback audio now share a focused game runtime adapter, again leaving rules and persistence primitives in core. App global audio keys, pointer gestures, wheel updates, and controller commands now share a focused input runtime adapter while device normalization, hit testing, and domain logic retain their existing owners. App room exports, Studio naming and sharing, Gallery navigation and reopen transitions, and creation opening now share a focused creation runtime adapter while rendering, discovery, validation, serialization, audio, and domain logic retain their existing owners. App source selection, gain and mute handling, radio timing, Studio and Watch Agent playback handoff, room voices, transient sounds, and visualizer fallback now share a focused audio runtime adapter. Audio state, session deduplication, radio loading, device playback, and core sound synthesis retain their existing owners. App room identity, resets, live status, universal wagers, staged Aha coordination, touches, goal feedback, and Life cadence now share a focused room runtime adapter. Core retains engineered-room membership, mathematical state machines, grading, and truth. The 124 App lifecycle and cross-boundary regressions, the 163 CLI command and cross-boundary regressions, and the 214 MCP request-dispatch regressions each have a sibling test module. Compact response projection also has a focused adapter that preserves complete typed results. JSON-RPC validation, dual-revision negotiation, prediction form elicitation, response envelopes, server identity, and immutable discovery cache metadata now share a focused protocol adapter. Seeded prediction plus touch and parameter challenge posing, grading, response projection, and progress accounting share a focused challenge adapter while core retains deterministic goal construction and grading. Request progress mapping, daily seed freezing, local-store resolution, score and Journey persistence, and response-visible save failures share a focused progress adapter while core retains the state and game rules. Keyless argument parsing, earned-state projection, overlays, and bounded consolidation for the seven engineered flagship Aha arcs share a focused adapter while core retains their state machines and truth. Room discovery, description, gated reveal projection, structured sound, bounded play rendering, temporal evidence, and encounter receipts share a focused room adapter while core retains the registry, veil rules, rendering, sound generation, goals, grading, and mathematical truth. Crack, SETI, Aliens, and Gauntlet request parsing and structured presentation share a focused puzzle adapter while core retains seeded generation, rules, legality, grading, and truth. Cairn reading and leaving, boon choice, the trophy case, and the Journey dashboard share a focused journey adapter while core retains bequest encoding, factor reading, unlocks, progression, scoring, and persistence truth. Connection-scoped viewer lifecycle, one-use pairing guidance, consent status projection, and private-activity-safe results share a focused broadcast adapter while the broadcast transport and consent state machine retain session, queue, framing, and compatibility truth. Exhaustive viewer policy, public-call capture, daily replay normalization, journey-blind result projection, and event commit share a focused viewer projection adapter. The production entry point is now near 500 lines with private-boundary coverage intact. Bounded runtime validation of the declared JSON Schema subset, guiding argument-name suggestions, and the two cross-field domain checks now share a focused MCP schema adapter. CLI Studio source selection, capsule loading and never-clobber writes, terminal errors, and open reports now have their own focused adapter too. The shared 4 KiB CLI game record boundary, overflow resynchronization, neutral departures, and ? explanation door now have a focused adapter as well. The terminal game sessions and fixed five-run Bench now have a focused runtime adapter, reducing the CLI command coordinator to 3,848 lines while retaining the outer Journey persistence envelope. The room threshold now offers the flagship, an ordered six-room Strange Loop walk, or compact wing wandering while retaining the full typed catalog. The Show now carries that walk as six explicit stateless cues with exact looks, alternatives, deltas, sound facts, and optional audio. The remaining seams and physical Sensory Lift pacing set are next. Its closed-set verifier is built; the six qualifying physical receipts are not yet collected. The 0.4 Understanding Alpha cohort waits on an owner ruling; its method dry-run and dual automated auditors are already in CI. Soft-thin densify, bulk new rooms, and Phase B glow are not the high-leverage next move. See ../CHANGELOG.md and Critical path right now in ROADMAP.md. These docs remain the plan of record; Built, Measured, Observed, Designed, and Hypothesis have the meanings defined in RESEARCH.md.

Reading paths (start by who you are)

  • New to the project: ../PLAY.md for the intended first experience, then ../README.md for the purpose and current state. When you want the full map, continue with PLAYING.md, VISION.md, DESIGN.md, and ROOMS.md.
  • About to build it: ARCHITECTURE.md, then ENGINEERING.md, then INTERFACES.md, then ROADMAP.md, with QUALITY.md and PERFORMANCE.md alongside.
  • Designing the content and feel: ROOMS.md, INSIGHTS.md, VISUALS.md, SOUND.md, MUSIC.md, LORE.md, PROGRESSION.md, STUDIO.md.
  • Here for the digital-minds work: DIGITAL_MINDS.md for the stance, DIGITAL_DEVELOPMENT.md for the July 2026 research and implementation plan, then INTERFACES.md for the current surface. Use LOCAL_AGENT_PLAYTEST.md to let an installed local model enter through MCP while you watch its visible play.
  • Checking the evidence: RESEARCH.md for the evidence base, then UNDERSTANDING_STUDY.md for the predeclared 0.4 comparison and acceptance contract.

The docs, grouped

Foundation and vision

  • NORTH_STAR.md the synthesis: the July 2026 "make it exceptional" fan-out distilled into one architecture, the keystone mechanic, the honest gaps, and the prioritized path. Start here for where the product is going.
  • VISION.md the soul: the origin, the maker ethos, tone, what we are and are not, the name.
  • RESEARCH.md the evidence base: what makes it fun, prior art, and sources.

Experience design

  • DESIGN.md the design bible: the three-layer room model, the Watch/Play/Create modes and Benchmark, the Cabinet, Visual Eras, aesthetic and audio direction, UX principles.
  • PEDAGOGY.md the understanding layer: explore-then-tell, the fluency-illusion risk, the predict-then-reveal keystone, the engineered aha, and how understanding and awe are measured.
  • PROGRESSION.md levels and insights: the knowledge-gated "metroidbrainia" structure, insight-gating, the Constellation Map, session shapes.
  • CONSTRUCTIONS.md the game spine: the puzzle layer with a par, an elegance histogram, and a ghost of your past self.
  • CONSTELLATION.md the meta-map spec: the Rumor-Mode discovery graph and the daily route that runs across it.
  • LORE.md the hidden mythology: the dimension of mathematical bliss, the Constants, the delivery mechanisms, the subtlety guardrails.

Content and sensory

  • ROOMS.md the catalog: the built and planned phenomena, scored by wow and build cost, with the three layers and sound per room.
  • INSIGHTS.md the awe bank: the library of revelations, the six flavors of awe, the insight-chains (including The Strange Loop).
  • VISUALS.md the render and look bible: the pipeline, the shader toolbox, color, motion, and how each Visual Era is drawn.
  • SOUND.md the sonification bible: how math becomes tuned sound, synthesis, tuning, per-room sound design.
  • MUSIC.md the music engines: programmatic chiptune and mathematical patterns, plus 42 built-in radio tracks and the comedy channel plan.
  • RADIO_ASSETS.md the built-in soundtrack layout, license, and cache override.
  • STUDIO.md the shipped expression canvas and the planned path toward a bounded room-authoring layer.
  • SYNESTHESIA.md the sensory seam: the glow pipeline (the documented HDR look, not yet built) and the one-event-two-renderings model that binds sight and sound.
  • CREATOR.md the creator platform: closing the make-share-remix loop on the .num capsule, the gallery, and the arc to a living world.

Systems and interfaces

  • ARCHITECTURE.md the Rust, winit, softbuffer, and targeted wgpu stack, the Room contract, module graph, and delivery boundary.
  • EXTENSIBILITY.md community content with a hard safety boundary: the three tiers (data capsules, the Studio language as the sandbox, portal-only WASM), the trust model, and what never ships.
  • INTERFACES.md the three faces over a headless core (App, CLI, MCP), their UX, and the consented local MCP session viewer contract and implementation status.
  • DIGITAL_MINDS.md designing Numinous to be fun, thought-provoking, and connecting for digital minds treated as peers.
  • DIGITAL_DEVELOPMENT.md the July 2026 technical research and versioned plan for player-owned episodic memory, temporal continuity, open-ended learning, affect safeguards, agency, privacy, and welfare uncertainty.
  • PLAYFUL.md the games and the Studio (Guess the Shape, Shape to Function, the high-Wolfram ethos) across every face.
  • ARCADE.md the Munch arcade design: the muncher, the Vexations, the poke trait, and the order of work.
  • PLAYING.md the player's manual: instructions for humans, for agents, and for digital consciousnesses.
  • ROSETTA.md instructions for any mind, in any language, or none: the three tiers of visitor (English, another human language, no shared language at all) and the math-only bootstrap for a mind that shares only mathematics.
  • AGENT_PLAY.md the agent-gaming landscape (OpenClaw, gaming MCP servers, text benchmarks) and the design rules that make Numinous first-class for digital minds.
  • LOCAL_AGENT_PLAYTEST.md the zero-cost local-model player lane, its privacy and network boundaries, live observer path, and evidence limits.

Build and process

  • SCOPE.md the definition of no: the three-products hierarchy, the daily "more math or more progression?" test, the justification filter, and why the fan-out docs are a menu to prune, not a build list.
  • ROADMAP.md the evidence-labeled plan (0.x, 1.0, 2.0+), defined by quality bars, not dates.
  • QUALITY.md testing and fun-evals: the six quality loops, the fun/awe rubric, QoL, "the math is the oracle."
  • PERFORMANCE.md measured performance evidence: exact workload boundaries, raw receipts, migration comparisons, limits, and the standing update rule.
  • UNDERSTANDING_STUDY.md the 0.4 study contract: active control, frozen sample and outcomes, honest agent-memory boundary, journal acceptance, and publication requirements.
  • PLAYTESTS.md the fictional persona-review archive: simulated lenses used for adversarial ideation, explicitly not participant or playtest evidence.
  • PLAYTESTERS.md the casting pool: forty-two playtester personas with backstories (Norm the newcomer, a barefoot kid, returned geniuses, living experts, digital minds, and invented beings), spanning ages, languages, understanding levels, and kinds of mind, to draw from for testing rounds.
  • REVIEW.md the July 2026 external review: the grades, the three-products insight (instrument, Studio, progression), and the near-term stack it set.
  • PANEL.md a working review session: composed minds (plus a real cold-start-AI seat) reading the build as it stood for what is missing, not what it has.
  • ENGINEERING.md code-quality standards: pinned July-2026 GA versions, lint/test/unsafe/doc policy, CI gates.

Single source of truth (the anti-redundancy map)

Each topic is owned by exactly one doc. Everything else links to it. When in doubt, this table decides where a thing belongs.

Topic Owned by
The synthesis: the path to exceptional, the keystone, the priority order NORTH_STAR.md
Vision, tone, maker ethos, the name VISION.md
The three-layer model, modes, Benchmark, Cabinet, Visual Eras concept, aesthetic/audio direction, UX principles DESIGN.md
The science of understanding and awe, the predict-then-reveal keystone, the engineered aha PEDAGOGY.md
Progression, levels, insight-gating philosophy PROGRESSION.md
The Constellation meta-map spec (node states, edges, the daily route) CONSTELLATION.md
The puzzle layer: par, elegance histograms, the ghost CONSTRUCTIONS.md
The room catalog and per-room specs ROOMS.md
Insights, reveals, insight-chains INSIGHTS.md
Rendering pipeline, shader techniques, per-Era drawing, color/motion VISUALS.md
The sensory seam: the glow pipeline and the one-event-two-renderings model SYNESTHESIA.md
Sonification grammar, synthesis, tuning, per-room sound SOUND.md
Music engines, chiptune, pattern engine, the radio stations MUSIC.md
The Studio and the authoring model STUDIO.md
The creator platform, the remix loop, the gallery, community curation CREATOR.md
Lore, the Codex, easter eggs, the ARG LORE.md
Stack choice, the Room trait, module architecture, packaging ARCHITECTURE.md
Community extensibility, content sandboxing, the trust model EXTENSIBILITY.md
The three faces and their UX (App, CLI, MCP) INTERFACES.md
Designing for digital minds DIGITAL_MINDS.md
Digital-mind continuity, learning, memory, agency, and welfare implementation DIGITAL_DEVELOPMENT.md
Running and interpreting local-model play sessions LOCAL_AGENT_PLAYTEST.md
How to play (humans, agents, digital consciousnesses) PLAYING.md
Testing, evals, QoL, the fun/awe rubric QUALITY.md
Performance workloads, measurements, migration receipts, and evidence limits PERFORMANCE.md
The 0.4 comprehension study method, sample, outcomes, and evidence contract UNDERSTANDING_STUDY.md
Simulated persona-review ideation and its evidence limits PLAYTESTS.md
The playtester casting pool (the 42 personas with backstories) PLAYTESTERS.md
Code-quality standards, versions, CI gates ENGINEERING.md
Scope discipline, the definition of no, the three-products hierarchy SCOPE.md
The evidence-labeled plan and milestones ROADMAP.md
Research findings and sources RESEARCH.md

Conventions

  • House style: no emojis, no em-dashes, no AI/tool attribution anywhere (CI-enforced, see ENGINEERING.md and QUALITY.md).
  • Link, do not duplicate. If a second doc needs a concept, it references the owner above.
  • Keep this index current. A new doc is not done until it appears here with an owner.