docs: sync README + CLAUDE.md with v0.6.18-0.6.21 merge sweep#273
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR updates top-level documentation to reflect the v0.6.18–v0.6.21 merge sweep, and also introduces/lands the Piper TTS embedded backend plus the /api/voice/synthesize API surface (including related API wiring, tests, and changelog updates).
Changes:
- Sync README + CLAUDE.md to reflect v0.6.21.0 status, package/app counts, and newly shipped voice + embedded runtime capabilities.
- Add
PiperTtsBackend(Piper CLI spawn wrapper) with model auto-detection + factory plumbing, and export it from@skytwin/embedded-llm. - Extend
/api/voiceto support TTS capabilities + synthesis, add route tests, and tighten ownership enforcement at the API mount point.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Updates version/status and “What works today” to include mobile voice capture + embedded LLM/voice endpoints. |
| CLAUDE.md | Updates package/app inventory entries to reflect embedded provider, authoring tier, mobile voice, and twin-mcp-server. |
| CHANGELOG.md | Adds an unreleased entry describing Piper TTS + /api/voice/synthesize and follow-up fixes. |
| packages/embedded-llm/src/piper-tts-backend.ts | Implements Piper TTS backend (spawn + temp WAV output) and model discovery helper. |
| packages/embedded-llm/src/tests/piper-tts-backend.test.ts | Adds unit tests for Piper backend behavior and model discovery. |
| packages/embedded-llm/src/factory.ts | Adds createEmbeddedTtsPort() factory (binary/model resolution + Null fallback). |
| packages/embedded-llm/src/index.ts | Exports Piper backend/types and the new TTS factory. |
| apps/api/src/routes/voice.ts | Adds TTS capability reporting + POST /synthesize; splits cached STT/TTS ports. |
| apps/api/src/index.ts | Mounts /api/voice behind requireOwnership (body userId enforcement). |
| apps/api/src/tests/voice-routes.test.ts | Adds/extends route tests for TTS capabilities + synthesize endpoint. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ## Project Status | ||
|
|
||
| SkyTwin is in **active development** (v0.5.4.0). The core decision pipeline, twin model, policy engine, and memory palace are functional. Gmail and Google Calendar connectors work with real OAuth. Desktop builds ship for all three platforms. The mobile app pairs via QR code. v0.5.0.0 brought the one-command installer and a non-technical-user UX overhaul; v0.5.1.0 through v0.5.4.0 closed the post-/review follow-ups. | ||
| SkyTwin is in **active development** (v0.6.21.0). The core decision pipeline, twin model, policy engine, and memory palace are functional. Gmail and Google Calendar connectors work with real OAuth. Desktop builds ship for all three platforms. The mobile app pairs via QR code and can capture voice. v0.5.0.0 brought the one-command installer and a non-technical-user UX overhaul; v0.5.1.0 through v0.5.4.0 closed the post-/review follow-ups; the v0.6 series added the embedded local LLM (#187), tier-aware memory retrieval (#251), per-Lifebook surfaces (#193), and the voice loop (mobile capture + Piper TTS). |
|
|
||
| - **`apps/api/src/routes/voice.ts`** — new `POST /api/voice/synthesize` | ||
| consumer. Body `{ userId, text, voice? }` → response | ||
| `{ audioBase64, durationBytes, voice }`. 503 + recovery hint when |
Comment on lines
+238
to
+241
| // /api/voice — `requireOwnership` enforces body/path/query userId matches the | ||
| // authenticated session. POST /transcribe + /synthesize take userId in the | ||
| // body, so the in-router :userId middleware alone wasn't sufficient — caught | ||
| // by Copilot on PR #255. |
Cross-references the 12 PRs that landed across #251 Layer 1+2+follow-ups (authoring tier, tier-weighted retrieval, pin/hide, backfill, real- embedding ablation), #193 Lifebook follow-ups (capabilities filter, provenance wing filter, per-Lifebook briefing), #179 mobile voice, and #187 AC#4 (Piper TTS) against the project's user-facing docs. README.md: - Version badge 0.6.17.0 → 0.6.21.0 - Package/app count "14 packages and 6 apps" → "29 packages and 7 apps" - Project Status reflects the v0.6 series (embedded LLM, tier-aware memory, per-Lifebook surfaces, voice loop) - "What works today" adds mobile voice capture + the on-device embedded LLM stack (llama.cpp / whisper.cpp / Piper TTS) with the /api/voice/transcribe and /api/voice/synthesize endpoints CLAUDE.md: - llm-client row notes the `embedded` provider and the estimateLlmCostCents() helper - New embedded-llm row covers llama.cpp / whisper.cpp / Piper TTS - connectors row notes the AuthoringTier classifier (#251 Layer 1) - memory-gbrain-crdb-adapter row notes Layer 2 tier-weighted RRF scoring, pin/hide controls (#270), and the backfill worker (#271) - mobile app row notes voice capture via expo-audio + the desktop transcribe round-trip - New twin-mcp-server app row No CHANGELOG changes — each PR's entry was authored by /ship and covers its own slice accurately. No TODOS.md changes — the two open P3s (real production tour mode, multi-instance demo rate limiting) remain blocked on the same product decisions; nothing in this sweep closes them. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
8393eb0 to
f5e1d3d
Compare
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Post-ship documentation sync for the 12 PRs that landed during the recent merge sweep:
/api/voice/synthesizeestimateLlmCostCents()helperWhat changed in docs
README.md
14 packages and 6 apps→29 packages and 7 appsllama.cpp/whisper.cpp/ Piper TTS) with the/api/voice/*endpointsCLAUDE.md
llm-clientrow notes theembeddedprovider +estimateLlmCostCents()embedded-llmpackage row covering llama.cpp text, whisper.cpp STT, and Piper TTSconnectorsrow notes theAuthoringTierclassifiermemory-gbrain-crdb-adapterrow notes Layer 2 tier-weighted RRF, pin/hide, and the backfill workermobileapp row notes voice capture viaexpo-audiotwin-mcp-serverapp rowTest plan
node --checkon the two changed files (markdown only — no executable changes)ls packages/,cat VERSION, etc.)Documentation
Cross-doc consistency checked:
VERSION(0.6.21.0) matches the README badgedocs/memory-swap.mdreferenced by README still exists/ship; per/document-releaserules we polish wording only and never clobber🤖 Generated with Claude Code