docs: hand-tune CLAUDE.md — identity, glossary, dataflow map, and alpha API posture - #672
docs: hand-tune CLAUDE.md — identity, glossary, dataflow map, and alpha API posture#672Quick104 wants to merge 3 commits into
Conversation
Captures the project's settled direction for agents and contributors: the cluster-first scale bet, open-platform stance, the core-vs-plugin rule, KISS taste, and the current QA-era posture. Deliberately names no other projects. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Borrowed from T3 Code's hand-written AGENTS.md structure: a glossary pinning the ambiguous nouns (account/profile, item/file, section, node, session, jellycompat/v1), a five-line dataflow map of scanner-to-playback, an explicit completeness checklist for client-visible changes, focused-tests-while- iterating guidance, and a severity marker on the irreversible gotchas. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Pre-lock, restructuring the API is in scope and larger coordinated sweeps are preferred over incremental breaks with compat shims. The additive-only rules become binding at v1 lock (1.0); until then they are the design target for new endpoints. The identity section now defers to the v1 rules section instead of stating its own strictness level. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Warning Review limit reachedYou’ve reached a temporary PR review limit under our Fair Usage Limits Policy. Next review available in: 29 minutes Limit details: You’ve used all 4 included reviews currently available. Your 69 included PR review attempts over the past 7 days set your current allowance at 4 reviews per hour. Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits within each organization. For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window. Please refer docs for additional details. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0769f9d465
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Media enters through the scanner (`internal/scanner`, fed by `scanqueue`/`autoscan`), is | ||
| classified by library kind (`librarykind`), ingested (`libraryingest`), and enriched by | ||
| metadata plugins into the catalog: `media_items` keyed by deterministic content IDs |
There was a problem hiding this comment.
The documented orchestration order is reversed: scanqueue.Service.process calls IngestFolder/IngestSubtree/IngestFile first (internal/scanqueue/service.go:364-371), and libraryingest.Executor.scan then invokes the scanner (internal/libraryingest/executor.go:482-500); autoscan also enqueues scan targets rather than feeding the scanner directly. Because this section is intended as the package-ownership map, describing scanner output as subsequently entering libraryingest will send changes to the wrong layer.
Useful? React with 👍 / 👎.
| - **Library** — a media folder with a kind (movies, TV, audiobooks, ebooks, podcasts). | ||
| - **Item vs file** — a `MediaItem` is a catalog entry (movie/series, `content_id` PK); a | ||
| `MediaFile` is one real file. One item can own many files (versions, extras, episodes). |
There was a problem hiding this comment.
The glossary omits a supported library type and narrows MediaItem too far: librarykind.Kinds includes dedicated Manga libraries (internal/librarykind/librarykind.go:14-38), while the scanners create media_items for audiobook, ebook, podcast, and manga content, not only movies and series. Agents using this taxonomy when updating catalog switches or API projections could therefore skip valid kinds; include manga in both library enumerations and define MediaItem to cover all top-level catalog item types.
Useful? React with 👍 / 👎.
| over the same catalog. Playback resolves a play method (`internal/playback`) — direct play, | ||
| direct stream, or transcode on a node from `nodepool` — and stream URLs are authorized by |
There was a problem hiding this comment.
The list does not match the internal/playback methods it claims to summarize: resolver.go:12-18 defines direct, remux, and transcode, while “direct stream” is terminology for serving the original file rather than a separate PlayMethod. Omitting remux from this package map can make work on container-only compatibility or copy-mode delivery appear to belong to the direct path, so name the actual three methods here.
Useful? React with 👍 / 👎.
| A modern, open-source media server built from the ground up on current infrastructure — | ||
| Postgres, S3, Redis — rather than SQLite and local disk. The foundational bet is horizontal | ||
| scale: Silo deploys as a cluster (Kubernetes, remote transcode nodes) and stays fast on large |
There was a problem hiding this comment.
Silo has not replaced local disk generally: users point the server at filesystem media folders (README.md:3), and integrated playback explicitly runs local transcodes when no remote node URL is assigned (internal/playback/session.go:36, internal/playback/transcode_manager.go:469-472). In an architecture guide, the unqualified “rather than … local disk” wording can incorrectly steer storage and single-node work away from supported local media and transient files; limit the contrast to the application state or asset data that is actually stored in Postgres/S3.
Useful? React with 👍 / 👎.
1 participant
Problem
CLAUDE.md told agents how to work in this repo but nothing about what Silo is — the scale bet, the core-vs-plugin rule, the current QA-era posture all lived only in the maintainer's head. It also pinned none of the project's ambiguous nouns (account/profile, item/file, session), and stated the v1 API rules more strictly than the actual pre-lock policy.
What this adds
Content comes from a maintainer interview; structure borrows from T3 Code's hand-written AGENTS.md (glossary, severity-ranked footguns, completeness checklist):
internal/.Notes
AI-use disclosure
Authored by Claude (Fable 5) via Claude Code from a maintainer interview; the maintainer set the content direction and reviewed the framing.
🤖 Generated with Claude Code