paseo-kanban 0.1.3 → 0.2.0

package/OVERVIEW.md

@@ -1,9 +1,37 @@
 # Kanban
 
-Organize tasks in customizable swimlanes, add descriptions and subtasks, and link tasks to Paseo projects. Drag cards to reorder them within a lane or move them between lanes.
+A lightweight, responsive Kanban board plugin for Paseo workspaces.
 
-Open the board from the sidebar or from a workspace's `+` menu. Workspace tabs initially filter to their project's tasks and can sit beside an agent or terminal using Paseo's native split controls. Each open board has its own project filter; all boards on the same host share tasks and lanes.
+## Features
 
-Board data is stored in Paseo's host-scoped plugin settings. Concurrent edits use revision checks so a stale edit cannot overwrite a newer board. If a project's name cannot be read, its stored ID remains available. If workspace project context is unavailable when the board opens, it initially shows all tasks.
+- **GitHub issue import**: Import up to 25 open issues from the project’s GitHub.com origin into a chosen lane. Tasks remain independent and link back to their source. Requires Git and an authenticated `gh` on the daemon machine.
+- **Flexible swimlanes**: Add, delete, and rename lanes.
+- **Rich task cards**: Edit task titles and multi-line descriptions, manage subtask checklists, and link tasks to Paseo projects.
+- **Task completion**: Check a card or drag it into the completion lane to finish; uncheck or drag out to restore.
+- **Workspace tabs and splits**: Open the board beside an agent or terminal with Paseo's native split controls, initially filtered to the workspace's project, or use the sidebar entry.
+- **Smooth drag and drop**: Support intra-lane reordering and cross-lane movement.
 
-Requires Paseo 0.8.0 or later. No accounts, tokens, or additional setup are required.
+## Storage and requirements
+
+- **Data and privacy**: Board data is stored locally in host-scoped plugin settings with revision checks for concurrent edits. Core board use requires no external service; optional GitHub import reads GitHub using the daemon machine’s existing `gh` authentication and copies selected issue content into local settings.
+- **Host requirement**: Paseo 0.11.4 or later.
+
+---
+
+# 看板 (Kanban)
+
+专为 Paseo 工作区打造的轻量响应式看板插件。
+
+## 核心功能
+
+- **GitHub Issue 导入**：从项目的 GitHub.com origin 选择 Open Issues，每次最多导入 25 项到指定泳道；任务独立管理并保留外链。需要在 daemon 所在机器安装 Git 并登录 `gh`。
+- **灵活的泳道管理**：支持泳道增删与改名。
+- **丰富的任务卡片**：支持任务标题与多行描述编辑、子步骤清单管理，以及关联 Paseo 项目。
+- **任务完成与恢复**：通过卡片勾选或拖入完成泳道标记完成；取消勾选或拖出即可恢复。
+- **工作区标签页与分屏**：支持通过 Paseo 原生分屏控件与 Agent、Terminal 并排打开，默认筛选工作区所属项目，或使用侧边栏入口。
+- **流畅拖拽交互**：支持同泳道排序与跨泳道状态流转。
+
+## 存储与要求
+
+- **数据与隐私**：看板数据保存在宿主本地插件设置中，具备版本并发冲突保护（CAS）。看板基础功能无需外部服务；可选的 GitHub 导入使用 daemon 所在机器的 `gh` 登录态读取 GitHub，并将选中的 Issue 内容复制到本地设置。
+- **宿主要求**：Paseo 0.11.4 或更高版本。

package/README.md

@@ -2,27 +2,53 @@
 
 [简体中文](./README.zh-CN.md)
 
-A lightweight, responsive Kanban board plugin for [Paseo](https://paseo.sh) workspaces. Organize tasks across customizable swimlanes, break them down into subtasks, associate cards with native Paseo projects, and manage workflow status with intuitive drag-and-drop.
+A lightweight, responsive Kanban board plugin for [Paseo](https://paseo.sh) workspaces.
+
+![Paseo Kanban Board](./assets/marketplace/board-0.1.3.png)
+
+---
+
+## Highlights
+
+- **Swimlane Management**: Freely add, rename, and delete custom swimlanes to organize tasks according to your team's workflow stages.
+- **Drag-and-Drop Interaction**: Fluid intra-lane reordering and cross-lane movement with animated drop-slot displacement, viewport edge auto-scrolling, and smooth drop-in feedback.
+- **GitHub Issue Import**: One-way import of open issues from the project repository's GitHub origin into a chosen lane, featuring pagination, repository-wide creation-time sorting, automatic deduplication, and source links.
 
 ---
 
-## Features
+## Other Features
 
-- **Flexible Swimlanes**: Three initial lanes that you can rename, with support for adding and deleting custom lanes.
 - **Rich Task Cards**:
-  - Task title and multi-line description.
-  - Subtasks checklist with completion toggles and live progress tracking.
-  - Native Paseo project association.
-- **Workspace Tabs and Splits**: Open the board beside an agent or terminal, initially filtered to the workspace's project. The sidebar remains available.
-- **Project Filtering**: Instantly filter board cards by linked Paseo project to keep context focused.
-- **Smooth Drag-and-Drop**: Real-time hit-testing for reordering cards within lanes and moving cards across lanes.
-- **Versioned State Persistence**: Persists board data through Paseo's settings API with optimistic concurrency control (CAS) to prevent race conditions and accidental overwrites.
+  - Task title and multi-line description editing (with resizable description area).
+  - Subtask checklists with live completion progress tracking.
+  - Link tasks to projects created in Paseo.
+- **Task Completion & Restoration**: Check a card or drag it into the completion lane to finish; uncheck or drag out to restore cards to their original ordinary swimlane.
+- **Workspace Tabs and Splits**: Open the board beside an agent or terminal with Paseo's native split controls, initially filtered to the workspace's project, or use the sidebar entry.
+- **Independent Project Filtering**: Filter cards by specific Paseo projects or view unassigned tasks without isolating the shared underlying board data.
+- **Host Storage & Concurrency Protection**: Board data is safely stored in host-scoped plugin settings with optimistic revision checks (CAS) to prevent silent overwrites and preserve form drafts.
+
+---
+
+## Screenshots
+
+### Board Overview
+
+![Board Overview](./assets/marketplace/board-0.1.3.png)
+
+### Task Details & Subtasks Checklist
+
+![Task Editor](./assets/marketplace/task-editor-0.1.3.png)
+
+### Workspace Tabs & Split Controls
+
+![Workspace Split](./assets/marketplace/workspace-split-0.1.3.png)
 
 ---
 
 ## Requirements
 
-- **Paseo host**: `>= 0.8.0` (declared in `paseo-plugin.json`). The host runs the plugin.
+- **Paseo host**: `>= 0.11.4` (declared in `paseo-plugin.json`). The host runs the plugin.
+- **GitHub import (optional)**: Install Git and GitHub CLI (`gh`) on the daemon machine, sign in with `gh auth login`, and configure the project repository’s `origin` on GitHub.com. Both public and authorized private repositories are supported.
 - **Development and CI**: Node.js 24 (pinned in `.nvmrc` and `.node-version`) for checks, TypeScript stripping, and native tests.
 
 ---
@@ -57,12 +83,10 @@ Verify that the plugin is running:
 paseo plugin ls
 ```
 
-Once active, open the board from either entry:
+Open the board from either entry:
 
 - **Sidebar → Kanban**: shows all tasks by default.
-- **Workspace → `+` → Kanban**: initially filters to the workspace's project, with other filters available. Use Paseo's native split controls to place it beside an agent or terminal.
-
-Both entries share tasks and lanes with full editing support; their filters are independent. Closing and reopening the board or restarting restores the entry's default filter. If workspace project context is unavailable, the board silently shows all tasks and keeps that filter even if context arrives later. Narrow splits retain horizontal lane scrolling.
+- **Workspace → `+` → Kanban**: initially filters to the workspace's project, with other filters available; use Paseo's native split controls to place it beside an agent or terminal.
 
 ### Local Development
 
@@ -95,13 +119,13 @@ Individual commands (`npm test`, `npm run typecheck`, `npm run lint`, `npm run f
 
 ## Releases
 
-See the [0.1.3 release notes](./docs/releases/0.1.3.md). Each release's npm package and GitHub Release share the same version tag; GitHub includes the verified npm tarball. `main` may contain changes beyond the latest release.
+See the [CHANGELOG](./CHANGELOG.md). Each release's npm package and GitHub Release share the same version tag; GitHub includes the verified npm tarball. `main` may contain changes beyond the latest release.
 
 ---
 
 ## Architecture & Design
 
-Core terminology and design decisions are documented in [`CONTEXT.md`](./CONTEXT.md) and [`docs/adr/`](./docs/adr/).
+Core terminology and design decisions are documented in [`GLOSSARY.md`](./GLOSSARY.md) and [`docs/adr/`](./docs/adr/).
 
 ---
 

package/README.zh-CN.md

@@ -2,27 +2,53 @@
 
 [English](./README.md)
 
-专为 [Paseo](https://paseo.sh) 工作区打造的轻量响应式看板插件。支持自定义泳道分类、任务子步骤细化、原生 Paseo 项目关联筛选，以及跨泳道流畅拖拽管理。
+专为 [Paseo](https://paseo.sh) 工作区打造的轻量响应式看板插件。
+
+![Paseo 看板全景概览](./assets/marketplace/board-0.1.3.png)
+
+---
+
+## 亮点特性
+
+- **泳道管理**：自由新增、重命名与删除自定义泳道，按团队工作流灵活组织任务流转阶段。
+- **拖拽交互**：流畅的同泳道排序与跨泳道状态流转，支持动态占位槽避让、视口边缘自动滚动与平滑落位动画。
+- **GitHub Issue 导入**：从项目关联的 GitHub 仓库单向导入 Open Issues 到指定泳道，具备分页、全仓库创建时间排序、自动去重及来源外链直达能力。
 
 ---
 
-## 核心功能
+## 其他特性
 
-- **灵活的泳道管理**：开箱即用三列基础泳道（`待规划`、`执行中`、`已完成`），支持自由添加、重命名与删除自定义泳道。
 - **丰富的任务卡片**：
-  - 任务标题与多行描述编辑。
-  - 子步骤清单支持独立增删改、完成状态勾选及实时进度展示。
-  - 支持关联本地已有的 Paseo 项目。
-- **工作区标签页与分屏**：与 Agent、Terminal 并排打开看板，默认筛选工作区所属项目；保留侧边栏入口。
-- **项目维度筛选**：一键按关联的 Paseo 项目过滤看板卡片，聚焦当前目标。
-- **流畅拖拽交互**：精准的拖拽命中测试（Hit-Testing），支持同泳道排序与跨泳道状态流转。
-- **版本化数据持久化**：通过 Paseo settings API 存储看板，使用乐观并发版本控制（CAS）处理多会话写入冲突。
+  - 任务标题与多行描述编辑（支持多行描述框拖拽调节高度）。
+  - 子步骤清单与完成进度实时统计。
+  - 支持将任务关联至 Paseo 中创建的项目。
+- **任务完成与恢复**：卡片左侧勾选复选框或拖入专用完成泳道即可标记完成；取消勾选或拖出即可无损恢复至原普通泳道。
+- **工作区标签页与分屏**：支持通过 Paseo 原生分屏控件与 Agent、终端任意并排打开，默认自动筛选当前工作区项目，亦可通过侧边栏独立打开。
+- **独立项目筛选**：支持按关联项目快速筛选或查看未关联任务，各打开窗口筛选独立且共享整板底层数据。
+- **宿主持久化与并发保护**：看板数据安全保存在宿主设置中，具备版本并发冲突保护（CAS），表单草稿与错误状态受保护不被静默覆盖。
+
+---
+
+## 界面预览
+
+### 看板全景
+
+![看板全景](./assets/marketplace/board-0.1.3.png)
+
+### 任务详情与子步骤
+
+![任务详情与子步骤](./assets/marketplace/task-editor-0.1.3.png)
+
+### 工作区标签页与分屏
+
+![工作区标签页与分屏](./assets/marketplace/workspace-split-0.1.3.png)
 
 ---
 
 ## 环境要求
 
-- **Paseo 宿主**：`>= 0.8.0`（声明于 `paseo-plugin.json`），由 Paseo 运行插件。
+- **Paseo 宿主**：`>= 0.11.4`（声明于 `paseo-plugin.json`），由 Paseo 运行插件。
+- **GitHub 导入（可选）**：在 daemon 所在机器安装 Git 与 GitHub CLI（`gh`），执行 `gh auth login`，并将项目仓库的 `origin` 配置为 GitHub.com 仓库；支持公开及有权访问的私有仓库。
 - **开发与 CI**：使用 Node.js 24（声明于 `.nvmrc` 与 `.node-version`）执行质量检查、TypeScript 类型擦除和原生测试。
 
 ---
@@ -57,13 +83,11 @@ paseo plugin add breathi3552/paseo-kanban --ref main
 paseo plugin ls
 ```
 
-状态显示为 `running` 后，可从两个入口打开看板：
+可从两个入口打开看板：
 
 - **侧边栏 → 看板**：默认展示全部任务。
 - **工作区 → `+` → 看板**：默认筛选工作区所属项目，可切换范围；使用 Paseo 原生分屏操作与 Agent、Terminal 等并排显示。
 
-两个入口共享任务和泳道，保留完整编辑能力，筛选互不影响。关闭重开或重启后恢复入口默认筛选。无法取得工作区所属项目时静默展示全部任务，本次打开期间不因项目上下文恢复而自动切换。窄分屏保持横向滚动浏览泳道。
-
 ### 本地开发与调试
 
 如需进行本地源码调试或二次开发：
@@ -95,13 +119,13 @@ npm run check
 
 ## 版本发布
 
-参见 [0.1.3 版本说明](./docs/releases/0.1.3.md)。每版 npm 包与 GitHub Release 对应同一个版本 tag，GitHub 附带经过验证的 npm tarball。`main` 可能包含最新发布版之后的改动。
+参见 [更新日志 (CHANGELOG)](./CHANGELOG.md)。每版 npm 包与 GitHub Release 对应同一个版本 tag，GitHub 附带经过验证的 npm tarball。`main` 可能包含最新发布版之后的改动。
 
 ---
 
 ## 架构设计
 
-核心术语和架构决策见 [`CONTEXT.md`](./CONTEXT.md) 与 [`docs/adr/`](./docs/adr/)。
+核心术语和架构决策见 [`GLOSSARY.md`](./GLOSSARY.md) 与 [`docs/adr/`](./docs/adr/)。
 
 ---