kandown 0.11.2 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +13 -4
  2. package/bin/kandown.js +226 -14
  3. package/bin/tui.js +12 -6
  4. package/dist/index.html +115 -115
  5. package/package.json +1 -1
  6. package/templates/AGENT.md +11 -8
  7. package/templates/AGENT_KANDOWN.md +15 -8
  8. package/templates/README.md +24 -20
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "kandown",
3
- "version": "0.11.2",
3
+ "version": "0.12.0",
4
4
  "description": "File-based Kanban engine backed by Markdown. Zero backend, AI-agent friendly.",
5
5
  "type": "module",
6
6
  "bin": {
package/templates/AGENT.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Kandown conventions for AI agents
2
2
 
3
- This project uses a file-based Kandown board located in `.kandown/`. Read this file before touching task files.
3
+ This project uses a file-based Kandown board. The config and web UI live in `.kandown/`; the task files live in `tasks/` at the project root. Read this file before touching task files.
4
4
 
5
5
  ## Source of truth
6
6
 
@@ -9,10 +9,13 @@ Tasks are the source of truth. There is no board index to maintain.
9
9
  ```
10
10
  .kandown/
11
11
  ├── kandown.json ← project settings and board columns
12
- ├── tasks/
13
- │ ├── t1.md ← task status, metadata, subtasks, notes, report
14
- │ └── ...
15
- └── kandown.html ← local web UI
12
+ ├── kandown.html ← local web UI
13
+ ├── AGENT.md ← this file
14
+ └── AGENT_KANDOWN.md ← full reference
15
+
16
+ tasks/
17
+ ├── t1.md ← task status, metadata, subtasks, notes, report
18
+ └── ...
16
19
  ```
17
20
 
18
21
  Columns are stored in `.kandown/kandown.json` under `board.columns`. A task belongs to a column through its frontmatter `status`.
@@ -83,7 +86,7 @@ report: |
83
86
 
84
87
  ## Creating tasks
85
88
 
86
- Create a new `tasks/<id>.md` file. Pick the next available ID by scanning filenames in `.kandown/tasks/`. Task IDs use the format `t<N>` (e.g. `t1`, `t2`, `t45`).
89
+ Create a new `tasks/<id>.md` file. Pick the next available ID by scanning filenames in `tasks/`. Task IDs use the format `t<N>` (e.g. `t1`, `t2`, `t45`).
87
90
 
88
91
  ## Mutation rules
89
92
 
@@ -94,8 +97,8 @@ Create a new `tasks/<id>.md` file. Pick the next available ID by scanning filena
94
97
  | Change title/priority/tags/assignee | Task file frontmatter only |
95
98
  | Change ownerType/tools | Task file frontmatter only |
96
99
  | Edit description/notes/subtasks/report | Task file body/frontmatter only |
97
- | Create task | Create one file in `.kandown/tasks/` |
98
- | Delete task | Delete its file from `.kandown/tasks/` |
100
+ | Create task | Create one file in `tasks/` |
101
+ | Delete task | Delete its file from `tasks/` |
99
102
 
100
103
  ## Scope control
101
104
 
package/templates/AGENT_KANDOWN.md CHANGED
@@ -2,13 +2,20 @@
2
2
 
3
3
  ## The System
4
4
 
5
- Kandown is a file-based Kanban backed by plain markdown. All task state lives in `.kandown/tasks/*.md` — no separate board index, no database.
5
+ Kandown is a file-based Kanban backed by plain markdown. All task state lives in `tasks/*.md` at the project root — no separate board index, no database.
6
6
 
7
7
  ```
8
- .kandown/
9
- ├── tasks/ # Task files (source of truth)
10
- ├── kandown.json # Board columns + project settings
11
- └── kandown.html # Web UI
8
+ .kandown/ # config, web UI, agent docs
9
+ ├── kandown.json # Board columns + project settings
10
+ ├── kandown.html # Web UI (single-file bundle)
11
+ ├── AGENT.md # AI-agent conventions
12
+ └── AGENT_KANDOWN.md # (this file) full reference
13
+
14
+ tasks/ # source of truth — one .md per task
15
+ ├── t1.md
16
+ ├── t2.md
17
+ └── archive/ # archived tasks (.md files moved here)
18
+ └── t99.md
12
19
  ```
13
20
 
14
21
  **Board columns** are configured in `kandown.json` at `board.columns`. Tasks without a `status` go to **Backlog**.
@@ -87,9 +94,9 @@ The `report:` field supports markdown and is displayed prominently in the UI. Wr
87
94
  | Reorder task | Task file: update `order:` in frontmatter |
88
95
  | Change title/priority/tags/assignee | Task file frontmatter |
89
96
  | Edit description/notes/subtasks | Task file body only |
90
- | Create task | Create one new `.kandown/tasks/t-NNN.md` |
97
+ | Create task | Create one new `tasks/t-NNN.md` |
91
98
  | Delete task | Delete the task file |
92
- | Create/rename/delete columns | `kandown.json` at `board.columns` |
99
+ | Create/rename/delete columns | `.kandown/kandown.json` at `board.columns` |
93
100
 
94
101
  **One task file = one source of truth.** Never maintain a separate board index.
95
102
 
@@ -143,4 +150,4 @@ Edge cases, gotchas.
143
150
 
144
151
  ## Stack
145
152
 
146
- React, Motion, Tailwind, Vite, Zustand, TypeScript, Node.js ESM CLI.
153
+ React, Motion, Tailwind, Vite, Zustand, TypeScript, Node.js ESM CLI.
package/templates/README.md CHANGED
@@ -1,31 +1,34 @@
1
- # .kandown/
1
+ # Kandown
2
2
 
3
3
  File-based kanban for this project. Zero install, zero backend, plain markdown on disk.
4
4
 
5
+ ## Layout
6
+
7
+ ```
8
+ .kandown/ # config, web UI, agent docs
9
+ ├── kandown.html # single-file web app — open this in your browser
10
+ ├── kandown.json # project preferences, columns, appearance
11
+ ├── AGENT.md # AI agent conventions
12
+ ├── AGENT_KANDOWN.md # full agent reference
13
+ └── README.md # this file
14
+
15
+ tasks/ # source of truth — one .md file per task
16
+ ├── t1.md
17
+ ├── t2.md
18
+ └── archive/ # archived tasks live here
19
+ ```
20
+
5
21
  ## Usage
6
22
 
7
- 1. Open `kandown.html` in Chrome, Edge, Brave or Opera (File System Access API required)
8
- 2. Click **Select folder** and pick this `.kandown/` directory, then grant read/write permission
23
+ 1. Open `.kandown/kandown.html` in Chrome, Edge, Brave or Opera (File System Access API required)
24
+ 2. Click **Select folder** and pick the **project root** (the parent of `.kandown/`), then grant read/write permission
9
25
  3. That's it
10
26
 
11
27
  The app remembers the last 10 projects you've opened — no need to re-select the folder each time.
12
28
 
13
- ## Structure
14
-
15
- ```
16
- .kandown/
17
- ├── tasks/
18
- │ ├── t1.md ← full task details
19
- │ └── ...
20
- ├── kandown.html ← the engine (single file, no dependencies)
21
- ├── kandown.json ← project preferences, columns, appearance, optional fields
22
- ├── AGENT.md ← AI coding agent conventions
23
- └── README.md ← this file
24
- ```
25
-
26
29
  ## Settings
27
30
 
28
- Open Settings from the app header to tune this project. Board columns are stored in `kandown.json` at `board.columns`. Each task chooses a column with its frontmatter `status`.
31
+ Open Settings from the app header to tune this project. Board columns are stored in `.kandown/kandown.json` at `board.columns`. Each task chooses a column with its frontmatter `status`.
29
32
 
30
33
  ## Editing without the app
31
34
 
@@ -33,17 +36,18 @@ Everything is plain markdown. Edit files directly in your IDE, Obsidian, or vim.
33
36
 
34
37
  ## For AI agents
35
38
 
36
- See `AGENT.md`. The key convention: each task file is its own source of truth. Moving a task means editing the task's frontmatter `status`.
39
+ See `AGENT.md` and `AGENT_KANDOWN.md`. The key convention: each task file in `tasks/` is its own source of truth. Moving a task means editing the task's frontmatter `status`.
37
40
 
38
41
  ## Keyboard shortcuts
39
42
 
40
43
  | Key | Action |
41
44
  |---|---|
42
45
  | `⌘K` / `Ctrl+K` | Command palette |
43
- | `⌘1` / `Ctrl+2` | Board / list view |
46
+ | `⌘1` / `Ctrl+1` | Board view |
47
+ | `⌘2` / `Ctrl+2` | List view |
44
48
  | `N` | New task |
45
49
  | `R` | Reload |
46
50
  | `/` | Focus search |
47
51
  | `Esc` | Close drawer / palette |
48
52
  | `⌘S` | Save current task |
49
- | `⌘⌫` | Delete task (with confirmation) |
53
+ | `⌘⌫` | Delete task (with confirmation) |