outcrop 0.1.0 → 0.1.2

package/docs/AGENTS.md

@@ -13,6 +13,7 @@ You are working in (or against) an outcrop workspace: a directory of plain markd
 
 - Frontmatter is flat `key: value` only: no nesting, no multiline values. Lists are inline (`depends_on: [ST-001, ST-002]`). Dates are `YYYY-MM-DD`.
 - Valid `status`: `backlog | ready | in-progress | in-review | done | blocked`. Valid `priority`: `P1 | P2 | P3`.
+- `order` is a number a human set by dragging a card. Leave it alone. Omit it on new tasks; never invent one to push your own work up the board.
 - Task body sections in fixed order: `## Description`, `## Subtasks`, `## Acceptance criteria`, `## Test steps`, `## Notes`.
 - Subtasks are `- [ ]` / `- [x]` checkboxes under `## Subtasks`. Do not reorder them: the API addresses checkboxes by index.
 - IDs: tasks `ST-###`, epics `E##`. Filenames: `ST-###-slug.md`, `E##-slug.md`. Bare ID mentions anywhere in the workspace auto-link; `depends_on` and `epic` create graph edges.

package/docs/API.md

@@ -68,13 +68,29 @@ Body: any of
 {
   "status": "in-review",
   "priority": "P2",
+  "epic": "E02",
+  "body": "## Subtasks\n\n- [ ] rewritten\n",
   "checkbox": { "index": 0, "checked": true },
   "rev": "1784910833019.7715"
 }
 ```
 
+- `body` replaces everything after the frontmatter. The frontmatter block is left byte-for-byte alone, so a body edit can never change an id, status, or rank. Over 1,000,000 characters is a `413`, never a silent truncation.
+
+Plus exactly one of these, to move the card within its column group (see [SPEC: Ordering](SPEC.md#ordering)):
+
+```json
+{ "move": "up" }          // or "down": swap with the neighbour
+{ "before": "ST-004" }    // place immediately above that task
+{ "after": "ST-004" }     // place immediately below it
+```
+
 - `rev` (recommended, from a prior GET): request is rejected if the file changed since. Omitting `rev` skips the check: last write wins. Multi-agent setups must send it.
 - Mutations are format-preserving: only the targeted frontmatter line or checkbox is rewritten.
+- A move is resolved against the destination, so `status` and `epic` in the same request are applied first: `{"status": "done", "before": "ST-004"}` moves the card to `done` and places it above ST-004 there.
+- `epic` must name an epic that exists, or the request is a 400. `""` clears it.
+- A move that would run past either end of the group is a no-op, not an error.
+- **A move can write more than one file.** Placing a card usually rewrites only its own `order`, but the first move in a never-ordered group stamps ranks on its siblings, and a group that runs out of room between two ranks is respaced. `rev` guards the named task only — the sibling writes are not checked.
 - With `BOARD_GIT_COMMIT=1`, each successful PATCH becomes a git commit (`ST-001: ready -> in-progress via board`).
 
 Responses:
@@ -83,12 +99,22 @@ Responses:
 |---|---|---|
 | 200 | applied | `{ "ok": true, "rev": "<new rev>" }` |
 | 200 (no-op) | nothing changed | `{ "ok": true, "rev": "...", "unchanged": true }` |
-| 400 | invalid status/priority/checkbox/JSON | `{ "error": "..." }` |
+| 400 | invalid status/priority/epic/checkbox/JSON, or a `before`/`after` target not in the group | `{ "error": "..." }` |
 | 404 | unknown id | `{ "error": "..." }` |
 | 409 | stale rev: file changed since read | `{ "error": "stale: ..." }` |
 
 On 409: re-GET the item, reconcile, retry with the new rev.
 
+### `GET /api/docs?file=REL.md`
+
+The markdown source of a document, which is what `/docs` renders rather than serves:
+
+```json
+{ "file": "NOTES.md", "body": "# Notes\n\n…", "rev": "1784910833019.7715" }
+```
+
+`body` excludes the frontmatter block, matching what `PATCH` writes back. `404` for an unknown or out-of-workspace file. This is what the in-page editor reads.
+
 ### `PATCH /api/docs?file=REL.md`
 
 Toggle a checkbox in a plain document, which has no id to address it by:
@@ -98,6 +124,15 @@ curl -X PATCH 'localhost:4311/api/docs?file=NOTES.md' -H 'content-type: applicat
   -d '{"checkbox":{"index":2,"checked":true},"rev":"<rev>"}'
 ```
 
+Or replace the whole body:
+
+```bash
+curl -X PATCH 'localhost:4311/api/docs?file=NOTES.md' -H 'content-type: application/json' \
+  -d '{"body":"# Notes\n\nRewritten.\n","rev":"<rev>"}'
+```
+
+`body` replaces everything after the frontmatter, which is preserved exactly. Over 1,000,000 characters is a `413`. A body identical to what is on disk is a `200` with `unchanged: true` and no write, so an editor that autosaves on a timer costs nothing when nothing was typed.
+
 Checkboxes only — a document is not a task, so there is no status or priority to set. `index` counts `- [ ]` / `- [x]` lines from the top of the file, skipping fenced code blocks, exactly as it does for a task. `rev` is optional and behaves as it does elsewhere: supply it and a concurrent change is a `409`. `404` for an unknown or out-of-workspace file, `400` for an index that does not exist.
 
 ### `POST /api/tasks`, `POST /api/epics`, `POST /api/docs`

package/docs/SPEC.md

@@ -38,12 +38,21 @@ epic: E01            # owning epic id
 status: ready        # default set: backlog | ready | in-progress | in-review | done | blocked
                      # a workspace can redefine this set via "columns" in .outcrop.json
 priority: P1         # P1 | P2 | P3
+order: 150           # optional manual rank inside its column and epic; see below
 depends_on: []       # list of task ids
 created: 2026-07-07
 ```
 
 Missing keys default to: `status: backlog`, `priority: P3`, empty strings/lists.
 
+#### Ordering
+
+The board draws each column grouped by `epic`, and each group sorted by `order` ascending. A task with no `order` sorts after every task that has one, falling back to priority then id. A workspace where nobody has reordered anything therefore looks exactly as it did before this key existed, and writing `order` is never required.
+
+`order` is any finite number, and the gaps are deliberate: the board writes ranks spaced by 100 so an insert between two cards is a midpoint and rewrites one file. When two neighbours are closer than `0.001` the whole group is respaced to `100, 200, 300, …` in one pass.
+
+Ranks are scoped to one column of one epic. The same value may appear in another column or under another epic without meaning anything. Moving a task between columns or epics leaves its `order` valid only for where it landed, so the board rewrites it on arrival.
+
 ### Epic keys
 
 ```yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "outcrop",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Serve a folder of markdown tasks and docs as a live kanban board, docs site, and agent API. AI-native, zero-config, files are the database.",
   "type": "module",
   "bin": {