docs(domains): add foundation domain READMEs (#966)

[oxoxDev]

Summary

• 12 NEW domain READMEs at strict 5-section template (Responsibility / Public surface / Calls into / Called by / Tests).
• Domains covered: agent, memory, channels, skills, cron, config, app_state, security, accessibility, local_ai, encryption, plus core/event_bus.
• 446 lines total across 12 files (31-44 lines each).

Problem

Foundation domains under `src/openhuman//` and `src/core/event_bus/` had no per-domain README. Engineers landing in a domain dir had to read `mod.rs` + `schemas.rs` + grep consumers themselves to build a mental model — every time. Sub-issue of #773 asked for one README per domain so this work happens once and stays current with the source.

Solution

Each README follows a fixed template:

• One-paragraph responsibility statement.
• Public surface — bulleted list of `pub` items + RPC methods with `file:line` refs.
• Calls into — other domains this one depends on.
• Called by — code paths that import from this domain (consumer grep).
• Tests — pointer to unit / integration / Vitest coverage.

Content is grounded in actual source: `pub fn`, `pub struct`, `pub trait`, `pub enum`, `pub use` were enumerated from each domain's top-level `*.rs` files; consumer lists from `use crate::openhuman::::` greps.

Submission Checklist

• Tests added or updated — N/A: docs-only PR, no code changes.
• Coverage matrix updated — N/A: no feature rows added/removed/renamed; READMEs are reference docs, not test layer changes.
• All affected feature IDs from the matrix are listed under `## Related` — N/A: no matrix rows touched.
• No new external network dependencies introduced.
• Manual smoke checklist updated if this touches release-cut surfaces — N/A: no release-cut surface changes.
• Linked issue closed via `Closes #NNN`.

Impact

• Runtime: zero. Markdown only.
• Build: zero. No `Cargo.toml` / `package.json` touched.
• Reviewer effort: 12 short additive files, each independently reviewable.
• Lychee: once [Test Infra] Tighten PR template + add CI enforcement for tests/docs #965 lands, the new pr-quality.yml link-check job will validate the relative refs across all 12 READMEs.

Related

• Closes [Docs] README sweep for foundational core domains #966
• Parent epic: Enforce unit tests, feature tests, and documentation for core foundation  #773
• Depends on (for CI gate): [Test Infra] Tighten PR template + add CI enforcement for tests/docs #965 (lychee glob includes `src/**/README.md`)
• Follow-up: encryption domain is a thin shim over credentials/ — candidate for refactor (separate PR, not blocking).

Summary by CodeRabbit

• Documentation
  • Added README docs for twelve core modules (event bus, accessibility, agent orchestration, app state, channels, config, cron, encryption, local AI, memory, security, skills), detailing each module’s responsibilities, public API/RPC surfaces, integration points, testing guidance, and examples for consumers (including event/request patterns and accessibility/agent behavior summaries).

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 085ee53c-c786-48ae-82ec-550da2b9c68a

📥 Commits

Reviewing files that changed from the base of the PR and between 5ab11df and 4557c95.

📒 Files selected for processing (1)

• src/core/event_bus/README.md

🚧 Files skipped from review as they are similar to previous changes (1)

• src/core/event_bus/README.md

---

📝 Walkthrough

Walkthrough

Adds README documentation files for the event bus and 11 openhuman domain modules. Changes are documentation-only and introduce module responsibility summaries, public surface listings, integration mappings, and test pointers.

Changes

Cohort / File(s)	Summary
Event Bus src/core/event_bus/README.md	New docs describing the in-process EventBus (tokio broadcast), DomainEvent catalog, EventHandler trait, global init/access (init_global, global), publish/subscribe semantics, TracingSubscriber, NativeRegistry request/response API, error cases, and testing notes.
Agent src/openhuman/agent/README.md	README for agent orchestration: agent/runtime lifecycle, sub-agent runner, tool dispatch, triage, builders, RPC endpoints, and integration points.
App State src/openhuman/app_state/README.md	Documents app-state snapshot types, async APIs (snapshot, update_local_state), RPC endpoints, ownership boundaries, and consumers.
Channels src/openhuman/channels/README.md	Docs for channel trait, message structs, provider re-exports, startup/doctor hooks, channels.* RPCs, and integration with agent/runtime and event-bus.
Config src/openhuman/config/README.md	Describes Config schema, per-domain config structs, daemon/runtime helpers, workspace identity helpers, RPC endpoints, and dependencies (TOML, encryption).
Cron src/openhuman/cron/README.md	Describes cron parsing, persistent job/run store, scheduler, delivery into agent/channel pipelines, public APIs, and test locations.
Encryption src/openhuman/encryption/README.md	Specifies persisted EncryptedPayload format, EncryptionKey derivation (Argon2id), encrypt/decrypt RPC shims, crypto deps, and callers.
Local AI src/openhuman/local_ai/README.md	Documents on-device inference stack: runtimes, routing, model/device presets, LocalAiService, RPC endpoints, asset management, and test serialization note.
Memory src/openhuman/memory/README.md	Interface/architecture map, memory traits, unified storage, ingestion pipeline, KV/graph/query APIs, RPC surface, and tests.
Security src/openhuman/security/README.md	Defines security trust boundaries, policy construction, sandbox trait/backends, audit/secret components, redact() semantics, and tests.
Accessibility src/openhuman/accessibility/README.md	Documents macOS FFI ownership, Swift helper process bridge, screen capture/focused-text inspection, permission detection, hotkey/overlay control, and public API surface.
Skills src/openhuman/skills/README.md	Describes skill discovery (SKILL.md), resource limits, install/uninstall APIs, injection heuristics, RPC endpoints, and public types/constants.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~4 minutes

Possibly related PRs

• Refactor core cross-domain flows onto event bus #468: README and docs overlap with event-bus DomainEvent variants and subscriber registration changes.

Suggested reviewers

• senamakel

Poem

🐇 I hopped through folders with a curious stare,
README sprouts blooming everywhere.
From bus to skills, I stitched each seam,
Now maps and guides light up the team.
Carrot cheers — docs tidy, neat, and fair!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'docs(domains): add foundation domain READMEs (#966)' clearly and concisely summarizes the main change—adding README documentation for foundational domains, directly matching the changeset.
Linked Issues check	✅ Passed	All 12 required domain READMEs (agent, memory, channels, skills, cron, config, app_state, security, accessibility, local_ai, encryption, core/event_bus) are present in the changeset and adhere to the prescribed template covering responsibility, public surface, calls into, called by, and tests.
Out of Scope Changes check	✅ Passed	The changeset is documentation-only (12 new README files with no code changes) and fully scoped to the linked issue #966 requirements; no unrelated or out-of-scope modifications are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/core/event_bus/README.md`:
- Line 9: The README entry for init_global is incorrect: update the description
for pub fn init_global(capacity: usize) -> &'static EventBus to state that it
initializes once and panics if called more than once (matching the
panic-on-second-init semantics in bus.rs), replacing the current “safe to call
repeatedly” wording so the docs align with the implementation.

In `@src/openhuman/agent/README.md`:
- Line 3: Update the README sentence that claims "prompt section data lives in
`context/`" to reflect that prompt plumbing was moved to the
openhuman::agent::prompts module (retain that context::prompt now acts only as a
shim), so change the wording to mention openhuman::agent::prompts and
context::prompt shim to match the module boundary described in mod.rs.

In `@src/openhuman/app_state/README.md`:
- Line 3: The opening responsibility sentence in the README currently reads
"Aggregator the React shell polls every few seconds..." which is missing a
connector; update that sentence to include the missing word (e.g., change to
"Aggregator that the React shell polls every few seconds..." or "Aggregator the
React shell polls every few seconds to render..." whichever matches tone) so it
reads grammatically correct—locate the sentence starting with "Aggregator the
React shell polls" in the README and replace it with the corrected wording.

In `@src/openhuman/skills/README.md`:
- Line 3: Update the README sentence that says the QuickJS-based runtime is
"removed" to avoid implying deletion: change it to state that this module "does
NOT own runtime execution internals" and note that the skills runtime uses
QuickJS (rquickjs) — i.e., remove the word "removed" and replace with a short
clause clarifying runtime execution (QuickJS/rquickjs) is handled elsewhere in
the skills codebase. Ensure the text still asserts that this component does not
manage runtime/tool execution.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7c4c5085-a4d9-4cd2-8a94-57f0f3ff0a83

📥 Commits

Reviewing files that changed from the base of the PR and between 1a25f5b and e902fdb.

📒 Files selected for processing (12)

• src/core/event_bus/README.md
• src/openhuman/accessibility/README.md
• src/openhuman/agent/README.md
• src/openhuman/app_state/README.md
• src/openhuman/channels/README.md
• src/openhuman/config/README.md
• src/openhuman/cron/README.md
• src/openhuman/encryption/README.md
• src/openhuman/local_ai/README.md
• src/openhuman/memory/README.md
• src/openhuman/security/README.md
• src/openhuman/skills/README.md