These documents describe development toward v1.0.0-alpha.1. Start with installation, v0.1.x upgrade, or the candidate release notes. Daily use is covered by Library/Media, live Locations, and the bundled CLI Skill.

Temporary Draft Compatibility Policy

The supported release sequence is v0.1.x → v1.0.0-alpha.1 → v1.0.0. Preserve legacy migration/import and a forward upgrade/import path for published v1 data. The persistence contract owns artifact identities and revisions independently of software versions. Alpha APIs may change with release notes; supported published data retains a path forward.

The temporary exception applies to unpublished Draft revisions: their schemas, APIs, Job bundles and backup formats do not require compatibility adapters. Reject unsupported development data without deleting installations or physical data; regenerate disposable fixtures explicitly. Withdrawn experimental installations require separately preserved data and an explicit reinstall; the public installer has no release-number downgrade exception.

Before the first stable v1 release, remove this temporary exception and its contributor reference, publish the stable API/upgrade policy, and audit stale Draft claims. The exception does not apply to v1.0.0-alpha.1 or later once published.

Current Architecture

Designs and Decisions

Requirements baseline: Online file management
Draft: Files interaction and metadata restore
Draft: v1 Alpha release and upgrade delivery
Candidate: v1 Alpha 1 changes and acceptance status
Accepted: File organization is independent of content
Superseded: Content identity owns Library organization

Operations

History

Implemented: Shared Files, query filters and configurable Scan
Superseded: Browsing, Restore association and copy integrity
Superseded: Online originals, File versions and archive copies
Implemented: Live Locations and persistent File organization
Implemented: Shared Library and Location organization
Implemented: Indexing workflows and CLI acceptance
Implemented: Locations and File content interface
Implemented: Content-grouped duplicates in Locations
Implemented: Online data-source design and acceptance
Platform design snapshot
Platform development change summary

Historical documents are frozen context, not the maintenance target for current behavior. Old document URLs remain as navigation stubs.

Documentation Convention

Location	Owns	Does not own
Root README	Product introduction, quick start, documentation entry points	Detailed architecture or repeated runbooks
Root CONTEXT	Domain vocabulary, core domain invariants, navigation	Schemas, algorithms, task notes
Root AGENTS	Contributor instructions, safety gates, required document updates	A duplicate architecture specification
`architecture`	Implemented behavior, boundaries, constraints, code anchors	Unimplemented proposals
`designs`	Proposed changes, interfaces, failure behavior, acceptance scenarios	Claims of current capability
`decisions`	Sparse numbered ADRs for durable, non-obvious tradeoffs	Routine implementation choices or discussion transcripts
`operations`	Setup, migration, maintenance, and reproducible validation	Another definition of the domain model
`history`	Implemented/superseded designs and historical development summaries	Current design authority

Use English Markdown, short topic-based kebab-case filenames, and repository-relative links. Current architecture filenames are version-independent; version names belong in migration guides and historical records. Link to the owning topic instead of repeating its definition. Link important claims to source files without duplicating generated schemas.

Update Workflow

Read the relevant current topic and glossary before changing its behavior. Check the implementation when documentation and code disagree.
Record confirmed domain terms and design constraints in their owning document during the task, not only in the final response. Keep unsettled or unimplemented behavior in a design marked Draft. Do not silently change code to resolve an uncertain discrepancy.
Update code, semantic tests, affected current documentation, and any affected operational or Demo guide together. A design describes scope, new boundaries/interfaces, data flow, failure semantics, compatibility, acceptance cases, and implementation order; include open questions only when unresolved.
After implementation and verification, update the current architecture, mark the design Implemented and move it to history. Mark replaced proposals Superseded and link their replacement. Update the index and preserve useful old entry points with short links.
Before delivery, check links, code anchors, status labels, and duplicate facts manually, and run git diff --check. No additional documentation toolchain or CI is required.

Record outcomes and durable maintenance rationale, never chat history, backtracking, or rejected work. ADRs use sequential names such as 0001-content-identity.md, a status, and a short decision/rationale; create one only when the choice is hard to reverse, surprising without context, and grounded in a real tradeoff.

UI Prototypes

Build UI prototypes in React using the existing application's components, styling, and layout. Capture the rendered pages in a browser; generated concept images are not UI specifications. Label proposed behavior and sample data explicitly.

Keep an independent page source and entry point for each prototype, with local run instructions and its screenshot. Shared application components and draft fixtures may be reused. Store temporary frontend prototypes under the ignored frontend/.drafts/ directory for review and implementation reference, then remove their code and screenshots before committing. Keep accepted behavior and constraints in the owning design document, independently of these disposable artifacts.