# 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.

## Tiers

Lanework ships as **one free Mac App Store app** with tiers from one codebase and one format (12-editions.md, re-ruled 2026-07-30): **Lanework** (free — no git; macOS-native undo — 13-native-undo.md), **Lanework Pro** (an auto-renewable subscription unlocking git-backed history, branches, remote sync — 06/07), and **Lanework Teams** (tracker integration over the reserved enhanced schema; deferred, probably a separate app). The deeper reason for the tier seam: history and sync live behind a provider boundary, 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).