docs: prepare GERM public alpha release

emeisazam · emeisazam · commit 7c45716a2aeb · 2026-07-15T07:21:02.000-05:00
diff --git a/CITATION.cff b/CITATION.cff
@@ -1,5 +1,5 @@
 cff-version: 1.2.0
-message: "If you use germ in research, please cite the companion Sonic Field Labs papers."
+message: "If you use GERM in research, please cite this software release."
 title: "germ: a lineage-aware cultivation environment for generative microsound"
 authors:
   - family-names: "Isaza"
@@ -10,21 +10,4 @@ date-released: "2026-07-02"
 license: "MPL-2.0"
 repository-code: "https://github.com/sonicfieldlabs/germ"
 abstract: "germ is a local generative microsound environment whose generated sounds retain prompts, parents, mutations, listening metadata, and Earworm-compatible lineage."
-preferred-citation:
-  type: article
-  title: "The Listening Stack: Agentic Sonic Computation for Hybrid Listening Ecologies"
-  authors:
-    - family-names: "Isaza"
-      given-names: "eme"
-      affiliation: "Sonic Field Labs"
-  year: 2026
-  notes: "Submission draft prepared for the Agentworld special issue of Antikythera: Journal for the Philosophy of Planetary Computation."
-references:
-  - type: article
-    title: "germ: Generative Cultivation and Sonic Lineage"
-    authors:
-      - family-names: "Isaza"
-        given-names: "eme"
-        affiliation: "Sonic Field Labs"
-    year: 2026
-    notes: "Companion paper in preparation."
+url: "https://sonicfield.org/stack"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,25 +1,65 @@
-# Contributing
+# Contributing to GERM
 
-germ is licensed under MPL-2.0. By contributing, you agree that your
-contribution is provided under the same license.
+GERM is a public-alpha cultivation environment and open research release.
+Contributions are welcome when they improve its sonic practice, lineage,
+provider accountability, safety, accessibility, or reproducibility.
 
-Keep the local-first contract intact:
+## Begin Here
 
-- Do not add cloud egress unless it is explicitly opt-in and documented.
-- Do not log secrets, tokens, absolute private paths, or raw prompt data beyond
-  the local metadata files the user asked germ to create.
-- Keep generated audio, uploads, scratch data, and personal `.env` files out of
-  git.
-- Add or update tests when changing API behavior, metadata lineage, storage, or
-  safety limits.
-- Update `docs/api_reference.md` when adding, removing, or renaming a FastAPI
-  route.
+1. Open an issue before a large graph, API, provider, or storage change.
+2. Fork the repository and create a focused branch.
+3. Install the model-free development environment:
 
-Before proposing a release change, run:
+   ```bash
+   uv sync --extra dev
+   ```
+
+4. Develop against the mock provider unless the change specifically concerns
+   a real provider. Tests and review must not require gated weights or a live
+   account.
+5. Add tests and public documentation, run the checks below, and describe any
+   lineage, storage, network, or licensing effect in the pull request.
+
+Do not commit model weights, generated audio, uploads, credentials, `.env`
+files, local paths, private prompts, personal sessions, or provider responses.
+
+## Contracts to Preserve
+
+- Cloud egress remains explicit, opt-in, and documented.
+- Secrets and absolute private paths never enter metadata, lineage, fixtures,
+  logs, screenshots, or documentation.
+- A generation enters Akousmata only through an explicit remember request.
+- Parentage, prompts, models, parameters, mutations, and listening references
+  remain inspectable rather than being flattened into one caption.
+- Server limits, path containment, and CV/MIDI safety gates remain testable.
+- API changes update `docs/api_reference.md`; provider changes update
+  `docs/provider_design.md` and model attribution where relevant.
+
+## Scoped Contribution Opportunities
+
+These public-alpha tasks have clear review boundaries:
+
+1. **Provider contract fixtures.** Add a mock or recorded-response fixture that
+   exercises readiness, progress, cancellation, error metadata, and output
+   validation without a network call or model weights.
+2. **Listening Stack round trip.** Extend a test for
+   Oída → GERM → Akousmata → Oída so parent identifiers, operation, prompt,
+   provider, retention choice, and fresh listening remain intact.
+3. **Dashboard accessibility.** Test one complete keyboard and screen-reader
+   path through adding a module, configuring it, starting a mock render, and
+   opening its result. Include visible focus and reduced-motion behavior.
+4. **Reproducible provider report.** Document one exact OS, CPU/GPU, Python,
+   provider revision, checkpoint, and short render result. Share metadata and
+   license-safe observations, never weights or copyrighted source audio.
+
+Small documentation fixes do not need an issue. Larger tasks should state
+acceptance criteria and which contract they touch.
+
+## Local Checks
 
 ```bash
-.venv/bin/pytest -q
-.venv/bin/ruff check server tests
+uv run pytest -q
+uv run ruff check server tests
 node --check dashboard/static/app.js
 node --check dashboard/static/dish.js
 node --check dashboard/static/micro_forms.js
@@ -29,3 +69,14 @@ node --check dashboard/static/ui_utils.js
 node --check dashboard/static/wavetable_synth.js
 node scripts/smoke_dashboard.mjs
 ```
+
+Use `./launch_germ.command` and the mock provider for a manual dashboard smoke
+test. Do not place the resulting runtime data in Git.
+
+## License and Rights
+
+GERM is licensed under MPL-2.0. By submitting a contribution, you confirm that
+you have the right to provide it under that license. Third-party code, model
+interfaces, fixtures, and media need explicit compatible provenance. See
+[models and licensing](docs/models-and-licensing.md) before adding a provider
+or checkpoint surface.
diff --git a/NOTICE b/NOTICE
@@ -18,5 +18,13 @@ stable-audio-3 @ git+https://github.com/Stability-AI/stable-audio-3.git
 That dependency is not vendored in this repository. Install it only if your use
 case and environment are compatible with the upstream project and model terms.
 
+The upstream Stable Audio 3 code repository currently identifies an MIT code
+license. Stable Audio model weights use separate model terms, including the
+Stability AI Community License for published Stable Audio 3 checkpoints. Those
+terms are not replaced by GERM's MPL-2.0 license.
+
 Earworm integration surfaces map germ metadata into Earworm 0.4-compatible
 sessions for local provenance, consent, retention, and lineage workflows.
+
+See docs/models-and-licensing.md for direct upstream references and the full
+operator responsibility boundary.
diff --git a/README.md b/README.md
@@ -1,14 +1,72 @@
 # GERM
 
-GERM is a local-first modular laboratory for generative microsound. It treats
-sound as matter that can be generated, granulated, mutated, routed, listened
-to, cultivated, and traced through lineage.
+> **Public alpha · Open research release · Local-first · Open-source · Under active development**
+
+GERM is a local cultivation environment for generative microsound. It treats
+sound as material that can be generated, granulated, grafted, mutated,
+listened to, and traced through lineage. A listening from Oída can become a
+prompt or source in GERM; a successful render can become a descendant in
+Akousmata and return to Oída for another listening.
 
 Current release: `0.2.0`.
 
 GERM is an independent Sonic Field Labs project. It can use Stable Audio 3
 providers, but it is not an official Stability AI product.
 
+![GERM dashboard with a prompt module in the cultivation graph](docs/assets/germ-dashboard.png)
+
+## Try It Without a Model
+
+The default mock provider exercises the dashboard, graph, jobs, metadata,
+lineage, and WAV-writing path without downloading a model:
+
+```bash
+uv sync --extra dev
+./launch_germ.command
+```
+
+Open `http://127.0.0.1:5178/dashboard`. The mock provider emits a test signal,
+not model-generated sound, so it is safe for installation and integration
+checks but not a creative quality demonstration.
+
+## What You Can Do
+
+- Generate or transform sound through mock, local Stable Audio 3 Python,
+  Apple Silicon MLX, or opt-in Stability API providers.
+- Build a modular graph across grains, cells, swarms, tissues, controls,
+  effects, and a realtime Chamber.
+- Graft, inpaint, continue, compare, mutate, record, and collect sound while
+  retaining prompts, seeds, models, parameters, parents, and operations.
+- Import an Oída listening as sound, prompt, or lineage and ask Oída to listen
+  to a cultivated result again.
+- Write a successful generation to the shared Akousmata store only when
+  requested.
+
+## Requirements
+
+| Path | Operating system | Hardware and software |
+| --- | --- | --- |
+| Mock service | macOS or Linux | Python 3.10+, `uv`; CPU only; no weights |
+| Stable Audio 3 MLX | Apple Silicon macOS | Official `sa3` MLX tools and separately accepted model weights |
+| Stable Audio 3 Python | Upstream-compatible macOS or Linux | Optional Python provider and hardware appropriate to the chosen checkpoint; a supported GPU is strongly recommended |
+| Stability API | Any service-supported system | Network access, an operator-owned account, API key, and acceptance of service terms |
+| Native shell | macOS 13+ | Swift 5.9/Xcode command-line tools; the Python service still performs all audio work |
+
+Model access, RAM or VRAM use, and generation time vary substantially by
+checkpoint and provider. GERM reports provider diagnostics rather than
+promising one universal hardware minimum.
+
+## Release Guide
+
+| Question | Where to begin |
+| --- | --- |
+| How does it work? | [Micro/Matter architecture](docs/germ_micro_architecture.md) and [provider design](docs/provider_design.md) |
+| How does it connect? | [The Listening Stack](https://sonicfield.org/stack) and [Oída integration](docs/oida-integration.md) |
+| Which models and licenses apply? | [Models and licensing](docs/models-and-licensing.md) |
+| What is unfinished? | [Known limitations](#known-limitations) and [roadmap](ROADMAP.md) |
+| How can I help? | [Contribution guide](CONTRIBUTING.md) |
+| How should I cite it? | [CITATION.cff](CITATION.cff) |
+
 ## What works
 
 - Text-to-audio generation, seed/batch variation, audio-to-audio grafting,
@@ -47,6 +105,11 @@ library, and lineage model.
 
 ## Listening Stack integration
 
+**Oída hears. GERM cultivates. Akousmata remembers. AKOÚŌ structures. Earworm
+routes.** Together they form
+[The Listening Stack](https://sonicfield.org/stack), open infrastructure for
+listening, re-listening, sonic memory, and cultivation.
+
 | Component | Version / contract | GERM integration |
 | --- | --- | --- |
 | [OÍDA](https://github.com/sonicfieldlabs/oida) | 0.6.0 / `oida/gateway/v0.2` | Re-listen to generated sound, derive editable prompts, and retain a listening only when requested. |
@@ -59,9 +122,12 @@ library, and lineage model.
 The core handoff is:
 
 ```text
-OÍDA listens → Akousmata remembers → GERM cultivates
-       ^                                  |
-       +----------- listen again --------+
+Sound → Oída hears → GERM cultivates → Akousmata remembers
+          ↑                 |                    |
+          +------------- listen again -----------+
+
+AKOÚŌ structures claims and routes. Earworm routes events,
+provenance, retention, and lineage between the organs.
 ```
 
 ## Install
@@ -164,6 +230,27 @@ curl -X POST http://127.0.0.1:5178/generate \
 - A generation written to Akousmata records only portable identifiers and
   relative/protocol-safe provenance. Machine-specific paths stay local.
 
+## Known Limitations
+
+- This is a public alpha. Session, graph, and provider interfaces can still
+  change before 1.0 even though public contracts are documented.
+- Jobs are held in memory. A server restart loses job state, while completed
+  WAV and metadata files remain on disk.
+- A queued Python-provider job can be cancelled, but an in-process render may
+  finish because the upstream API has no safe mid-render interrupt. MLX
+  subprocess jobs support active cancellation.
+- Real-model access is separately licensed and may be gated. Output quality,
+  latency, determinism, and hardware use vary by provider and checkpoint.
+- The native macOS shell is built locally and is unsigned by default.
+- Physical CV output is disabled. MIDI may use browser Web MIDI or an optional
+  configured local backend; otherwise the server records intent only.
+- Hosted routes are explicit opt-ins and can send prompts, source audio, or
+  derived material to their provider. The default mock route stays local.
+- GERM performs bounded signal checks but does not replace Oída's listening and
+  claim-accountability layer.
+
+The [roadmap](ROADMAP.md) identifies current research priorities and non-goals.
+
 ## Development
 
 ```bash
@@ -184,6 +271,8 @@ node scripts/smoke_dashboard.mjs
 - [Local setup](docs/local_setup.md)
 - [Native macOS shell](docs/macos-shell.md)
 - [Troubleshooting](docs/troubleshooting.md)
+- [Models and licensing](docs/models-and-licensing.md)
+- [Public roadmap](ROADMAP.md)
 - [Changelog](CHANGELOG.md)
 
 ## License
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -0,0 +1,47 @@
+# GERM Roadmap
+
+GERM 0.2.0 is a public alpha and open research release. This roadmap names the
+work in view without promising dates or production stability.
+
+## Working Now
+
+- A model-free mock route for installation, interface, metadata, and lineage
+  testing.
+- Stable Audio 3 Python, Apple Silicon MLX, and opt-in Stability API provider
+  surfaces.
+- Modular Micro/Matter graph, realtime Chamber, library, Herbarium, strains,
+  wavetables, controls, sessions, and generation lineage.
+- Oída import and re-listening with explicit Akousmata memory writes.
+- A shared browser dashboard and native macOS shell over one server-owned
+  state.
+
+## Next Research Priorities
+
+- Expand provider contract fixtures for readiness, progress, cancellation,
+  timeouts, metadata, and failure recovery.
+- Strengthen round-trip lineage tests across Oída, GERM, Earworm, and
+  Akousmata.
+- Improve keyboard, screen-reader, reduced-motion, and low-vision access to the
+  modular graph and Chamber.
+- Publish reproducible performance and memory reports for verified provider,
+  checkpoint, and hardware combinations.
+- Make provider, model, LoRA, license, and source-listening attribution easier
+  to inspect and export.
+- Test durable job recovery designs without hiding partial or failed renders.
+
+## Toward a Stable Contract
+
+- Stabilize import, generation, job, and lineage schemas from public use.
+- Document migrations for sessions, graph state, strains, and metadata.
+- Broaden reproducible packaging beyond the source-based macOS shell.
+- Clarify which controller outputs are active, simulated, browser-routed, or
+  intentionally disabled.
+
+## Non-Goals
+
+GERM is not intended to hide model provenance, treat every generation as an
+original without ancestry, infer rights from a prompt, or enable uncalibrated
+physical CV output. Local-first is a technical boundary, not an automatic
+claim of ethical or ecological adequacy.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for scoped ways to participate.
diff --git a/docs/assets/germ-dashboard.png b/docs/assets/germ-dashboard.png
diff --git a/docs/models-and-licensing.md b/docs/models-and-licensing.md
@@ -0,0 +1,58 @@
+# Models and Licensing
+
+GERM starts with a mock provider that needs no model. Stable Audio 3 code,
+weights, hosted services, LoRAs, datasets, and accounts are optional operator
+choices and are not bundled in this repository.
+
+## Repository License
+
+GERM source code is licensed under MPL-2.0. That license covers this
+repository's code. It does not grant rights to third-party models, datasets,
+source recordings, provider services, or generated material.
+
+## Stable Audio 3 Code and Weights
+
+The optional Python provider references the official
+[Stable Audio 3 repository](https://github.com/Stability-AI/stable-audio-3).
+Its repository [code license](https://github.com/Stability-AI/stable-audio-3/blob/main/LICENSE)
+is MIT at the time of this release.
+
+Stable Audio 3 model weights are separately licensed. For example, the
+[Stable Audio 3 Small SFX model card](https://huggingface.co/stabilityai/stable-audio-3-small-sfx)
+identifies the Stability AI Community License and may identify additional
+component terms. Some checkpoints are gated. The upstream model card and terms
+for the exact checkpoint always control.
+
+GERM does not redistribute weights or accept upstream terms for the operator.
+Before installing a model:
+
+- review the code, weight, component, dataset, and commercial-use terms;
+- record the exact checkpoint and revision used;
+- confirm that the hardware and dependency combination is supported upstream;
+- retain any attribution or notice required for publication or distribution.
+
+The MLX installer prepares the official provider path on Apple Silicon; it
+does not change the model's license.
+
+## Stability API and Other Providers
+
+The Stability API route is opt-in and uses an operator-supplied key. Service
+terms, availability, credit use, retention, and content rules are separate
+from GERM. Requests can include prompts and source audio, so enable it only
+after deciding that transfer is appropriate.
+
+LoRAs and future adapters can have their own licenses and training-data
+constraints. GERM's Strain registry records declared identity, strength,
+tags, license, and provenance, but it cannot verify that a declaration is
+correct.
+
+## Audio and Research Outputs
+
+GERM does not determine ownership of input recordings, prompts, generated
+audio, lineage notes, or research exports. Operators are responsible for
+consent, provenance, attribution, and the rights required to create, store,
+perform, publish, or redistribute them.
+
+Use [CITATION.cff](../CITATION.cff) to cite GERM. Cite the exact model,
+checkpoint, provider, and relevant upstream release separately when they
+contributed to a result.
diff --git a/docs/oida-integration.md b/docs/oida-integration.md
