Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions docs/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ Prefer designs that allow this state to be reused across Library, Series, Downlo

The extended Seerr/discovery functionality is intended to become one coherent optional product capability.

Do not introduce dependencies that break or materially change normal Wholphin/Jellyfin behavior when the extended feature set is disabled or unavailable.
Do not introduce dependencies that break or materially change inherited Wholphin/Jellyfin behavior when the extended feature set is disabled or unavailable.

Prefer graceful degradation.

Expand All @@ -112,7 +112,7 @@ Current library diagnostics answer a different question:

- Is the content that should exist actually playable in Jellyfin?

For TV seasons, Wholphin may persist trusted released-episode expectations so a later visit can compare them with a fresh Jellyfin inventory even after acquisition history has expired or Seerr is unavailable.
For TV seasons, Mosaic may persist trusted released-episode expectations so a later visit can compare them with a fresh Jellyfin inventory even after acquisition history has expired or Seerr is unavailable.

Do not persist complete/incomplete conclusions, live Jellyfin counts, missing-episode results, or acquisition-adjusted status. Those values are ephemeral and must be calculated from persisted expectations, fresh Jellyfin playability, and current acquisition evidence.

Expand Down Expand Up @@ -161,7 +161,8 @@ Use the repository documents deliberately:
- `docs/UPSTREAM_SYNC.md` holds permanent branching and upstream-sync policy.
- `docs/MOSAIC_ROADMAP.md` holds durable product and engineering direction.
- `docs/ARCHITECTURE.md` holds stable application and engineering architecture.
- `docs/CODEX_HANDOFF.md` holds current and historical implementation continuity, non-obvious discoveries, rejected approaches, merge resolutions, and validation results.
- `docs/CODEX_HANDOFF.md` holds current implementation continuity, unresolved risks, and non-obvious
negative knowledge. Completed chronology belongs in `docs/history/README.md`.

During development, preserve information in this file whenever losing it
would make a future agent materially less effective or force it to
Expand Down
15 changes: 7 additions & 8 deletions docs/CODEX_HANDOFF.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

## Current checkpoint

T0-3 documentation consolidation D1–D5 is complete. D6 is defining the public/Wiki boundary; D7
final consistency remains open. T0-3 and Baseline T0 are not complete.
T0-3 Documentation, Wiki & Roadmap consolidation is complete through D7. The next checkpoint is
the separately authorized Baseline T0 final acceptance and closure. Baseline T0 is not yet complete.

Current repository identity is exactly `constbogdan/Mosaic`; upstream remains
`damontecres/Wholphin`. Work begins from current protected `origin/main` on a purpose-specific
Expand All @@ -30,11 +30,10 @@ not current instruction.

## Immediate continuity

- D6 owns public product guidance, contributor routing, and the rule that optional Wiki content
cannot replace versioned engineering authority. Wiki publication remains a separate operator
action.
- D7 will own the final documentation consistency and status audit. Do not declare T0-3 or Baseline
T0 complete before that separately reviewed acceptance.
- Do not declare Baseline T0 complete until its independent final acceptance is explicitly
performed and authorized.
- Public guidance is versioned in the repository. Optional Wiki publication remains a separate
operator action and cannot replace engineering authority.

## Non-obvious invariants and negative knowledge

Expand Down Expand Up @@ -79,7 +78,7 @@ rather than silently publishing a rewritten snapshot.

## Open risks and questions

- The current documentation phase still needs D6 and D7 acceptance.
- Baseline T0 still requires its independent final acceptance and closure decision.
- External GitHub settings remain manually administered; documentation may describe them, but no
configuration doctor or scheduled drift monitor is justified without repeated evidence.
- Android TV visual/focus/device behavior is not fully proven by hosted compilation and JVM tests.
Expand Down
12 changes: 5 additions & 7 deletions docs/MOSAIC_ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,17 +9,15 @@ the [documentation index](README.md).
- T0-1 validation, operator UX, and pipeline simplification — complete.
- T0-2 bounded authority/bootstrap/diagnostic corrections — complete.
- T0-3.0 Mosaic identity establishment — complete.
- T0-3 documentation consolidation — D1–D5 complete; D6 public/Wiki boundary is in progress and D7
remains open.
- T0-3 Documentation, Wiki & Roadmap consolidation — complete through D7.

Baseline T0 remains open until the separately defined T0-3 completion and final consistency work is
accepted. Current D6 work does not declare either T0-3 or Baseline T0 complete.
Baseline T0 remains open until its independent final acceptance is performed and authorized.
Completing T0-3 does not itself declare Baseline T0 complete.

## Current priorities

1. Complete D6 public/Wiki boundary work; no Wiki publication is implied.
2. D7: final documentation consistency, link, ownership, and status audit.
3. Resume evidence-driven product work from the feature roadmap below.
1. Perform the separately authorized Baseline T0 final acceptance and closure.
2. Resume evidence-driven product work from the feature roadmap below after that decision.

## Product direction

Expand Down
4 changes: 4 additions & 0 deletions docs/OBSERVED_MINOR_ISSUES.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@ Small, non-blocking issues observed during development or manual validation.

These items should be preserved for later review but should not interrupt the current implementation unless they become functionally significant. When an issue is fixed, record the resolution before removing or marking it resolved.

This is an observation ledger, not the product roadmap, issue tracker, architecture owner, or
operating authority. [MOSAIC_ROADMAP.md](MOSAIC_ROADMAP.md) owns priorities and direction. Moving
these observations to GitHub Issues requires a separate explicit decision.

## Open

### Series Details — Incomplete badge briefly flickers during initial load
Expand Down
8 changes: 4 additions & 4 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,10 +47,10 @@ continuity, and point-in-time evidence.
program are going.
- **Current continuity** — [Codex handoff](CODEX_HANDOFF.md): what a future engineering session
cannot safely infer from code alone.
- **Current issue ledger** — [Observed minor issues](OBSERVED_MINOR_ISSUES.md): bounded open and
resolved product observations.
- **Current planning record** — [T0-3 documentation consolidation plan](T0_3_DOCUMENTATION_CONSOLIDATION_PLAN.md):
reviewed ownership, consolidation sequence, and acceptance criteria for this documentation phase.
- **Current observation ledger** — [Observed minor issues](OBSERVED_MINOR_ISSUES.md): bounded open
and resolved observations; it is not the roadmap or an operating authority.
- **Completed program record** — [T0-3 documentation consolidation plan](T0_3_DOCUMENTATION_CONSOLIDATION_PLAN.md):
reviewed ownership, implementation sequence, and completion criteria for the documentation phase.

## Engineering architecture

Expand Down
36 changes: 29 additions & 7 deletions docs/T0_3_DOCUMENTATION_CONSOLIDATION_PLAN.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# T0-3 documentation consolidation audit and plan

Status: **D1-D5 COMPLETE; D6 implemented pending review. D7 has not begun.**
Status: **T0-3 Documentation, Wiki & Roadmap consolidation — COMPLETE. D1-D7 complete.**

This audit describes the documentation set at `main` commit
`44564901cbdb7ffce4b1c0704aa2d53f93c40fa9`. It does not move, delete, rename, or broadly rewrite
existing documents. T0-3 and Baseline T0 remain open. The next checkpoint requires separate review
and authorization.
existing documents. T0-3 is now complete; Baseline T0 remains open and its final acceptance requires
separate review and authorization.

## Principles

Expand Down Expand Up @@ -386,7 +386,29 @@ GitHub Wiki is therefore an optional presentation layer: it may summarize user-f
must link its versioned repository source, cannot own engineering or security contracts, and may be
published only through a separate explicit operator action.

`docs/README.md` now distinguishes public product documentation, contributor orientation,
versioned engineering authority, current continuity, history, and the optional Wiki boundary. No
validation, publication, signing, provenance, Hold, repository-authentication, or upstream contract
changed. D7 remains the final consistency and status audit; T0-3 and Baseline T0 remain open.
At D6 closure, `docs/README.md` distinguished public product documentation, contributor
orientation, versioned engineering authority, current continuity, history, and the optional Wiki
boundary. No validation, publication, signing, provenance, Hold, repository-authentication, or
upstream contract changed. D7 and Baseline T0 acceptance remained open.

## D7 completion audit

D7 reconciled current checkpoint wording after the D6 merge and audited the complete documentation
system for ownership, naming, links, anchors, agent bootstrap, public/Wiki boundaries, history, and
machine-adjacent consumers. Every topic in the canonical matrix has one current owner. The root
README now exposes the versioned user guide directly; contributor documents route to repository
authority; the observation ledger explicitly does not compete with the roadmap or operating docs.

Current Wholphin occurrences are limited to upstream identity, inherited source/package names,
stable machine protocols, or truthful historical evidence. The established historical roadmap,
identity record, and pre-D5 handoff remain clearly non-operational and discoverable through the
history index. `AGENTS.md` is the general authority, `UI_AGENTS.md` is a bounded extension, and the
live handoff remains limited to current continuity and negative knowledge.

Repository-wide Markdown links and heading anchors, canonical-path searches, machine/config path
tests, changed-scope pre-commit, whitespace validation, and Fast validation pass. D7 creates no
Wiki, changes no operating contract, and performs no historical restructuring.

All T0-3 completion criteria below are satisfied. **T0-3 Documentation, Wiki & Roadmap
consolidation is COMPLETE.** Baseline T0 remains open; its independent final acceptance and closure
is the next checkpoint and is not authorized or performed by D7.
12 changes: 6 additions & 6 deletions docs/UPSTREAM_SYNC.md
Original file line number Diff line number Diff line change
Expand Up @@ -466,16 +466,16 @@ GitHub documents approval-required PR workflow runs for token-created PRs, while
App installation tokens allow the normal unattended trigger path:
[GITHUB_TOKEN behavior](https://docs.github.com/en/actions/concepts/security/github_token).

The user confirmed external setup complete on 2026-09-09: **Wholphin Sync Bot** was installed on
the downstream repository with Contents read/write, Pull requests read/write and Metadata read.
After R2, the same installation follows repository ID `1351255476` and selects
`constbogdan/Mosaic`; no App configuration or permission changed. Repository variable
The user confirmed external setup complete on 2026-09-09: the App then named **Wholphin Sync Bot**
was installed on the downstream repository with Contents read/write, Pull requests read/write and
Metadata read. R2 renamed its display metadata to **Mosaic Sync Bot**; the same installation follows
repository ID `1351255476` and selects `constbogdan/Mosaic` with no permission widening. Repository variable
`SYNC_BOT_CLIENT_ID` and secret `SYNC_BOT_PRIVATE_KEY` remain configured. The earlier empty-secret
result is historical.

The pinned official `actions/create-github-app-token` v3 action uses `client-id` and `private-key`,
restricts `owner`/`repositories` to the current downstream identity only after it authenticates as
one of the two exact R1 names, and requests only Contents/PR write. The key is supplied only to the
restricts `owner`/`repositories` to `constbogdan/Mosaic` only after exact current-repository
authentication, and requests only Contents/PR write. The key is supplied only to the
token action and only when ready, REVIEW or semantic-conflict state requires a branch/PR mutation.
Excluded and no-delta paths never mint it. Default job-completion token revocation remains enabled.
No PAT fallback or additional App permissions are introduced.
Expand Down
Loading