rzen
cacd48cb0f
Edition split follow-through: 12-editions.md and 13-native-undo.md join the corpus; git-era docs (06, 07) are Pro-scoped and cross-references realigned. Resolution session rulings written in place: caret chords yield to any focused text control (04, 11); the drop settle holds its proposal as overlay state and 02 gains the overlays family; Duplicate gets the save-panel fallback and a cancellable copy walk (03); Finder open is a standard document open (02); failed first opens record before loading with the folder name provisional (02); trash pointer ranges skip by kind, full-height marquee surface, Select All by kind, rows-only trashed universe (02, 04); Empty Trash counts entries (03); create handoff reads as one arrival (02); range-anchor lifecycle, board- background click grammar, jump landing cards, lane-domain shift-arrows (04); Reduce Motion restated per voice (10). Claude-Session: https://claude.ai/code/session_01CqjXB7ASoWtbyoGod68k97
54 lines
5.3 KiB
Markdown
54 lines
5.3 KiB
Markdown
# Vision
|
|
|
|
## What Lanework is
|
|
|
|
A native macOS kanban app whose storage is **plain folders + Markdown files**. Every board, lane, and card is a folder containing an `index.md` (YAML frontmatter + Markdown body). The filesystem is the source of truth; the app is a live view over it.
|
|
|
|
The defining consequence: **anything that can read and write files is a first-class user of a board** — text editors, Finder, shell scripts, git, and above all AI agents. Claude Code working in a repo can file, move, and annotate cards with zero API, zero sync machinery, zero app-specific tooling. The app's job is to be the best *human* surface over that substrate.
|
|
|
|
## Who it's for
|
|
|
|
- Individuals and small teams who want their planning data in files they own — greppable, diffable, versionable, portable.
|
|
- Developers who live in git and want boards to ride along with (or next to) their repos.
|
|
- People working *with* AI agents, who want the agent and the human looking at the same board through their respective native surfaces (files for the agent, a polished Mac app for the human).
|
|
|
|
## Design principles
|
|
|
|
1. **Files first.** Every feature must degrade gracefully to "it's just folders of Markdown." If the app vanishes, the data remains fully usable.
|
|
2. **The app never surprises the file.** Unknown frontmatter keys survive verbatim; untouched bodies are never rewritten; writes are atomic. Hand edits and app edits coexist without ceremony.
|
|
3. **Fail fast on malformed input.** A broken file surfaces a loud, specific error with the offending path — never partial loads, never data loss by "repair," never a rewrite of anyone's bytes. The one scoped softening is 01-storage-format.md's read-side rescue family (duplicate-key last-wins, the unquoted-colon recovery): an obvious hand-editor slip reads as what the writer meant — silently, with a log line, bytes preserved verbatim — because bricking a board over a recoverable slip fails files-first harder than leniency does. Fail-fast keeps guarding structure the rescues can't legitimize.
|
|
4. **Native to the bone.** SwiftUI, macOS conventions (Finder-style rename, ⌥-drag copy, package documents, real windows), no web tech, no JS runtime.
|
|
5. **Agents are users, not integrations.** The schema, the agent guide, and the tolerance rules are designed for programmatic writers from day one.
|
|
|
|
## Editions
|
|
|
|
Lanework ships as three editions from one codebase and one format (12-editions.md): **Lanework** (no git; macOS-native undo — 13-native-undo.md), **Lanework Pro** (git-backed history, branches, remote sync — 06/07), and **Lanework Teams** (Pro plus tracker integration over the reserved enhanced schema; deferred). Separate Mac App Store apps sharing the `.kanban` UTI — any board opens in any edition. The deeper reason for the split: history and sync live behind a provider seam, so Teams' sync can be backend-agnostic (git *and* trackers) instead of git being load-bearing everywhere.
|
|
|
|
## App identity
|
|
|
|
The previous version was a **pathfinder** — it never shipped. This rewrite is the app. It keeps the internal codename `Kanban` (Xcode target, scheme, bundle id `dev.rzen.indie.Kanban`) and ships under the display name **Lanework**. Because nothing shipped, there is no migration story and no compatibility obligation to pathfinder boards; the schema number stays `1`, redefined by this design (see 01-storage-format.md).
|
|
|
|
## Goals for the rewrite
|
|
|
|
- Preserve the on-disk philosophy and the interaction quality of the pathfinder while restructuring the schema and codebase with what we learned.
|
|
- Promote **attachments** to a first-class schema citizen.
|
|
- Split the schema into a **core schema** (this version: boards, lanes, cards, attachments) and an **enhanced schema** (comments, tracker fields) that is reserved but out of scope — see 01-storage-format.md.
|
|
- Build the **collab integration** axis (local-only / git) into the design from the start instead of retrofitting it.
|
|
- Keep the codebase honest about its layering: storage contract → store → views, with the cache rebuildable and the flow one-way.
|
|
- **Keyboard navigation as first-class UX** — the board fully operable without the mouse (04-interactions.md).
|
|
- **Accessibility is a requirement of "native to the bone," not an afterthought.** The keyboard-first contract doubles as the drag-free operation guarantee — that's the floor. VoiceOver correctness on the custom board, text scaling, and the system visual accommodations are designed in 10-accessibility.md.
|
|
|
|
## Non-goals
|
|
|
|
- No web or iOS version (design shouldn't preclude iOS forever, but nothing is compromised for it now).
|
|
- No MDX, no embedded scripting, no plugin runtime.
|
|
- No wiki-style cross-linking between cards (considered and punted — overkill for kanban).
|
|
- No tracker integrations (Gitea/GitHub/GitLab/Jira boards) in this scope — the schema reserves `remote`/`remote-state` so a future connector isn't foreclosed, but nothing here is designed for them.
|
|
- No comments functionality in this version — `comments/` is reserved in the enhanced schema for future integrations.
|
|
- No server. Sync rides on git remotes — never on infrastructure we run.
|
|
- No iCloud Drive boards. The app warns against placing a board in iCloud Drive (thorough explanation, git recommended instead) and makes no iCloud accommodations — see 07-sync-collab.md.
|
|
|
|
## Open questions
|
|
|
|
None currently — identity and migration are settled (see App identity above).
|