Repository navigation
Development
Start with CONTRIBUTING.md: focused fixes, simplification, architecture, compatibility evidence, and ownership matter more than adding code. Discuss substantial changes in an issue first.
| Topic | Resource |
|---|---|
| Build, signing caveats, host and Swift tests | [[Building and Signing |
| Layers, startup, recovery, and teardown | [[Architecture Overview |
| FireWire/OHCI background and references | [[FireWire Fundamentals |
| Current audio model and historical semantic design | [[Audio Semantics |
| Hardware evidence and reporting | [[Device Compatibility |
| Engineering constraints | CLAUDE.md |
| Audio publication/recovery shell | AudioDeviceHost contract |
| Empirical AudioDriverKit lab | ADKVirtualAudioLab |
Repository research notes may describe superseded experiments. Validate them against source, history, tests, and relevant behavioral references before treating them as a current contract. Do not copy reference implementations into the driver.
The ASFW app hosts a developer-only MCP endpoint, disabled by default and bound to
http://127.0.0.1:8766/mcp. Keep it on localhost and enable it only for active diagnostics.
It crosses the existing app/driver connector, not a separate driver or audio path.
Read asfw://control-plane/health first. It reports ready/degraded/unavailable state,
reasons and expected generation; deeper queries should respect that health and generation.
Use the app's Run read-only smoke action for a bounded hardware check.
Read/inspection tools and guarded writes have distinct policy gates. Some advertised capabilities remain unavailable; report the gap rather than inventing state or using a write as a substitute. Tool availability changes with the checked-out build, so inspect its catalog/health instead of maintaining a second static schema table here. Raw register/FCP/CAS operations can affect real hardware and need explicit authorization for the exact action; an agent/client flag never bypasses server policy.
The repository includes a Codex client skill:
mkdir -p ~/.codex/skills
cp -R skills/asfw-mcp-control-plane ~/.codex/skills/
python3 ~/.codex/skills/asfw-mcp-control-plane/scripts/asfw_mcp.py health
python3 ~/.codex/skills/asfw-mcp-control-plane/scripts/asfw_mcp.py summaryRun the copy commands from the repository root. health and summary are inspection
entry points; preserve returned generation information for subsequent bus requests.
Versioned details remain in the repository: architecture, tool taxonomy, telemetry resources, mock/smoke harness, and agent workflows.