trekoon 0.2.9 → 0.3.1

package/docs/quickstart.md

@@ -75,20 +75,19 @@ Current runtime expectations for operators:
 
 - the served HTML, styles, and board app files come from the local
   `.trekoon/board` runtime directory
-- the current shell also pulls Vue from `unpkg.com`, Tailwind from
-  `cdn.tailwindcss.com`, and Google-hosted fonts/icons at page load time
-- if those hosts are unavailable, the command still starts the loopback server
-  and prints the fallback URL, but the shell may not fully hydrate in the
-  browser until network access is available again
+- all assets are self-hosted: the board ships its own CSS, fonts (Inter,
+  Material Symbols), and vanilla JS with no framework or CDN dependencies
+- the board works fully offline once the runtime assets are copied into
+  `.trekoon/board`
 
 Current layout behavior:
 
 - the topbar is a compact navbar with workspace identity, Epics and Board
   navigation, debounced search, theme toggle, and workspace info
-- on wide displays, expect a three-surface workspace: epic switcher sidebar,
-  task workspace, and task inspector
-- on medium and small displays, secondary surfaces collapse into stacked panels
-  or drawer-style views so the board remains navigable on narrower widths
+- the board toggles between an epics overview and a task workspace view; task
+  detail opens as a modal overlay
+- responsive breakpoints adjust kanban column counts and component spacing so
+  the board remains navigable on narrower widths
 - the page scrolls naturally as one document; modal overlays lock body scroll
   while open
 - task cards show truncated descriptions; clicking a card opens the task detail
@@ -106,9 +105,8 @@ Verification checklist for operators:
    the search input while typing.
 4. Click a task card and confirm the task detail modal opens with the full
    description, edit form, and subtask list.
-5. On desktop width, confirm the epic switcher sidebar, workspace, and detail
-   panel can all be visible simultaneously.
-6. Resize to a narrow viewport and confirm the layout stacks cleanly without
+5. On desktop width, confirm the kanban board shows multiple columns.
+6. Resize to a narrow viewport and confirm columns reflow cleanly without
    horizontal overflow.
 7. Close modals and confirm you return to the previous board context.
 
@@ -200,6 +198,37 @@ Rules:
 - If any epic/task descendant is blocked by an unresolved external dependency,
   the whole cascade fails with no partial writes
 
+## Check progress and get suggestions
+
+After creating work, use `epic progress` to see status counts and the next ready
+candidate:
+
+```bash
+trekoon epic progress <epic-id>
+```
+
+Use `suggest` for priority-ranked next-action recommendations:
+
+```bash
+trekoon suggest
+trekoon suggest --epic <epic-id>
+```
+
+## Status machine
+
+Trekoon enforces valid status transitions. The canonical statuses are `todo`,
+`in_progress`, `done`, and `blocked`. Direct jumps like `todo → done` are
+rejected — use `task done` which auto-transitions through `in_progress`.
+
+Valid transitions:
+
+| From | Allowed targets |
+| --- | --- |
+| `todo` | `in_progress`, `blocked` |
+| `in_progress` | `done`, `blocked` |
+| `blocked` | `in_progress`, `todo` |
+| `done` | `in_progress` |
+
 ## What to read next
 
 - [Command reference](commands.md)

package/package.json

@@ -1,8 +1,30 @@
 {
   "name": "trekoon",
-  "version": "0.2.9",
+  "version": "0.3.1",
   "description": "AI-first local issue tracker CLI.",
+  "keywords": [
+    "ai",
+    "agent",
+    "skill",
+    "cli",
+    "board",
+    "tracker",
+    "agent-tracker",
+    "issue-tracker",
+    "task-tracker",
+    "local-first",
+    "planning",
+    "worktree"
+  ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KristjanPikhof/Trekoon.git"
+  },
+  "homepage": "https://github.com/KristjanPikhof/Trekoon#readme",
+  "bugs": {
+    "url": "https://github.com/KristjanPikhof/Trekoon/issues"
+  },
   "type": "module",
   "bin": {
     "trekoon": "./bin/trekoon"

package/src/board/assets/app.js

@@ -525,6 +525,7 @@ export async function bootLegacyBoard(options = {}) {
       showBoard: () => actions.showBoard(),
       scrollToDetail: () => document.querySelector(".board-drawer, .board-task-modal")?.scrollIntoView({ block: "nearest", behavior: getScrollBehavior() }),
       setView: (view) => actions.setView(view),
+      copyEpicId: (id) => actions.copyEpicId(id),
       toggleTheme: () => actions.toggleTheme(),
       toggleNotesPanel: () => actions.toggleNotesPanel(),
       confirmDelete: () => {

package/src/board/assets/components/EpicRow.js

@@ -2,6 +2,8 @@ import {
   escapeHtml,
   formatDate,
   neutralChipClasses,
+  renderCheckIcon,
+  renderCopyIcon,
   renderIcon,
   renderStatusBadge,
 } from "./helpers.js";
@@ -12,34 +14,47 @@ import {
  * @param {object} props
  * @param {object} props.epic
  * @param {boolean} [props.selected]
+ * @param {boolean} [props.copied]
  * @returns {string}
  */
 export function renderEpicRow(props) {
-  const { epic, selected = false } = props;
+  const { epic, selected = false, copied = false } = props;
 
   const totalTasks = Array.isArray(epic.taskIds) ? epic.taskIds.length : 0;
   const counts = epic.counts || { blocked: 0, done: 0, in_progress: 0 };
   const statusLabel = String(epic.status ?? "todo").replace(/_/g, " ");
   const openLabel = `Open epic ${epic.title}`;
   const tooltip = `${openLabel}. ${totalTasks} task${totalTasks === 1 ? "" : "s"}.`;
+  const copyLabel = `Copy epic UUID for ${epic.title}`;
+  const copyTooltip = `Copy epic UUID ${epic.id}.`;
   const descriptionMarkup = epic.description?.trim()
     ? `<p class="board-epic-row__description text-sm text-[var(--board-text-muted)] board-clamped-text__preview board-clamped-text__preview--2">${escapeHtml(epic.description.trim())}</p>`
     : "";
 
   return `
-    <button
-      type="button"
+    <div
       class="board-epic-row ${selected ? "board-epic-row--selected" : ""}"
+      role="button"
+      tabindex="0"
       aria-current="${selected}"
       aria-label="${escapeHtml(`${openLabel}. ${totalTasks} tasks. Status ${statusLabel}.`)}"
       title="${escapeHtml(tooltip)}"
       data-open-epic="${escapeHtml(epic.id)}"
     >
       <span class="board-epic-row__summary">
-        <span class="board-epic-row__title-row">
+        <span class="board-epic-row__meta-row">
           <span class="${neutralChipClasses()}">${escapeHtml(epic.id)}</span>
-          <strong class="board-epic-row__title">${escapeHtml(epic.title)}</strong>
+          <button
+            type="button"
+            class="board-copy-btn board-copy-btn--icon board-copy-btn--epic-row ${copied ? "board-copy-btn--active" : ""}"
+            data-copy-epic-id="${escapeHtml(epic.id)}"
+            aria-label="${escapeHtml(copied ? `Copied epic UUID for ${epic.title}` : copyLabel)}"
+            title="${escapeHtml(copied ? "Epic UUID copied." : copyTooltip)}"
+          >
+            ${copied ? renderCheckIcon("board-inline-icon--sm") : renderCopyIcon("board-inline-icon--sm")}
+          </button>
         </span>
+        <strong class="board-epic-row__title">${escapeHtml(epic.title)}</strong>
         ${descriptionMarkup}
       </span>
       <span class="board-epic-row__status">${renderStatusBadge(epic.status ?? "todo")}</span>
@@ -59,6 +74,6 @@ export function renderEpicRow(props) {
           ${renderIcon("chevron_right", "text-[16px]")}
         </span>
       </span>
-    </button>
+    </div>
   `;
 }

package/src/board/assets/components/EpicsOverview.js

@@ -43,7 +43,11 @@ function render(props) {
           <div class="board-table__rows board-table__rows--epics">
             ${visibleEpics.length === 0
               ? renderEmptyState("No matching epics", "Try a different search or publish more work to the board.", "/")
-              : visibleEpics.map((epic) => renderEpicRow({ epic, selected: selectedEpicId === epic.id })).join("")}
+              : visibleEpics.map((epic) => renderEpicRow({
+                epic,
+                selected: selectedEpicId === epic.id,
+                copied: store.copyFeedback?.epicId === epic.id,
+              })).join("")}
           </div>
         </div>
       </section>

package/src/board/assets/components/Notice.js

@@ -1,8 +1,7 @@
 import {
   escapeHtml,
-  panelClasses,
+  renderCheckIcon,
   renderIcon,
-  sectionLabelClasses,
 } from "./helpers.js";
 
 /**
@@ -27,7 +26,7 @@ export function createNotice() {
     },
 
     /**
-     * @param {{ notice: { type: string, message: string } | null, onDismiss?: () => void }} props
+     * @param {{ notice: { type: string, message: string, title?: string } | null, onDismiss?: () => void }} props
      */
     update(props) {
       if (!container) return;
@@ -47,16 +46,24 @@ export function createNotice() {
         return;
       }
 
+      const noticeTitle = typeof notice.title === "string" && notice.title.trim().length > 0
+        ? notice.title.trim()
+        : notice.type === "error"
+          ? "Action blocked"
+          : "Saved";
+
       container.innerHTML = `
-        <section class="${panelClasses("mb-4 flex items-start gap-3 p-4 sm:p-5")}" role="${notice.type === "error" ? "alert" : "status"}" aria-live="${notice.type === "error" ? "assertive" : "polite"}" aria-atomic="true">
-          <div class="flex h-10 w-10 shrink-0 items-center justify-center rounded-2xl ${notice.type === "error" ? "bg-red-500/10 text-red-300 ring-1 ring-red-500/20" : "bg-emerald-500/10 text-emerald-300 ring-1 ring-emerald-500/20"}">
-            ${renderIcon(notice.type === "error" ? "warning" : "check_circle", "text-[20px]")}
-          </div>
-          <div class="min-w-0">
-            <p class="${sectionLabelClasses()}" id="board-notice-title">${notice.type === "error" ? "Action blocked" : "Saved"}</p>
-            <p class="mt-1 text-sm leading-6 text-[var(--board-text-muted)]">${escapeHtml(notice.message)}</p>
-          </div>
-        </section>
+        <div class="board-toast-region" role="presentation">
+          <section class="board-toast board-toast--${notice.type === "error" ? "error" : "success"}" role="${notice.type === "error" ? "alert" : "status"}" aria-live="${notice.type === "error" ? "assertive" : "polite"}" aria-atomic="true">
+            <div class="board-toast__icon ${notice.type === "error" ? "board-toast__icon--error" : "board-toast__icon--success"}">
+              ${notice.type === "error" ? renderIcon("warning") : renderCheckIcon()}
+            </div>
+            <div class="board-toast__content">
+              <p class="board-toast__title" id="board-notice-title">${escapeHtml(noticeTitle)}</p>
+              <p class="board-toast__message">${escapeHtml(notice.message)}</p>
+            </div>
+          </section>
+        </div>
       `;
       lastNotice = { type: notice.type, message: notice.message };
 

package/src/board/assets/components/Workspace.js

@@ -8,6 +8,8 @@ import {
   neutralChipClasses,
   panelClasses,
   readStatusLabel,
+  renderCheckIcon,
+  renderCopyIcon,
   renderEpicCountSummary,
   renderEmptyState,
   renderIcon,
@@ -62,6 +64,9 @@ function renderWorkspaceHeader(props) {
   const epicSelectTooltip = "Switch the workspace to a different epic.";
   const bulkStatusTooltip = "Set the same status for every task in this epic.";
   const notesTooltip = "Show or hide this epic's description.";
+  const copyTooltip = "Copy this epic's UUID.";
+  const copyLabel = `Copy epic UUID for ${selectedEpic.title}`;
+  const isCopied = store.copyFeedback?.epicId === selectedEpic.id;
   const notesPanelId = `board-notes-panel-${selectedEpic.id}`;
   const orderedEpics = orderEpicsNewestFirst(snapshotEpics);
 
@@ -104,12 +109,17 @@ function renderWorkspaceHeader(props) {
 
       <div class="board-wh__row-2">
         <div class="board-wh__meta">
+          <span class="${neutralChipClasses()}">${escapeHtml(selectedEpic.id)}</span>
           ${renderEpicCountSummary(selectedEpic)}
           <span class="${neutralChipClasses()}">${visibleTasks.length} visible</span>
           ${store.isMutating ? `<span class="${neutralChipClasses()}">Saving\u2026</span>` : ""}
         </div>
         <div class="board-wh__actions">
           <div class="board-wh__action-group">
+            <button type="button" class="board-copy-btn ${isCopied ? "board-copy-btn--active" : ""}" data-copy-epic-id="${escapeHtml(selectedEpic.id)}" aria-label="${escapeHtml(isCopied ? `Copied epic UUID for ${selectedEpic.title}` : copyLabel)}" title="${escapeHtml(isCopied ? "Epic UUID copied." : copyTooltip)}">
+              ${isCopied ? renderCheckIcon() : renderCopyIcon()}
+              <span class="board-copy-btn__label">${isCopied ? "Copied" : "Copy ID"}</span>
+            </button>
             ${description ? `
               <button type="button" class="board-wh__notes-btn ${store.notesPanelOpen ? "board-wh__notes-btn--active" : ""}" data-toggle-notes aria-label="Toggle epic notes" aria-expanded="${store.notesPanelOpen}" aria-controls="${escapeHtml(notesPanelId)}" title="${escapeHtml(notesTooltip)}">
                 ${renderIcon("subject", "text-[16px]")}
@@ -255,11 +265,12 @@ function render(props) {
   const headerMarkup = renderWorkspaceHeader({
     selectedEpic,
     snapshotEpics,
-    store: {
-      notesPanelOpen: store.notesPanelOpen,
-      isMutating: store.isMutating,
-      selectedEpicId: selectedEpic.id,
-      view: store.view,
+      store: {
+        copyFeedback: store.copyFeedback,
+        notesPanelOpen: store.notesPanelOpen,
+        isMutating: store.isMutating,
+        selectedEpicId: selectedEpic.id,
+        view: store.view,
       viewModes,
     },
     visibleTasks,

package/src/board/assets/components/helpers.js

@@ -88,6 +88,23 @@ export function renderIcon(name, className = "") {
   return `<span class="${cx("material-symbols-rounded shrink-0", className)}" aria-hidden="true">${name}</span>`;
 }
 
+export function renderCopyIcon(className = "") {
+  return `
+    <svg class="${cx("board-inline-icon", className)}" aria-hidden="true" viewBox="0 0 16 16" fill="none">
+      <rect x="5" y="2.75" width="7" height="9" rx="1.5" stroke="currentColor" stroke-width="1.35"></rect>
+      <path d="M4 5.75H3.5C2.67157 5.75 2 6.42157 2 7.25V12C2 12.8284 2.67157 13.5 3.5 13.5H8.25C9.07843 13.5 9.75 12.8284 9.75 12V11.5" stroke="currentColor" stroke-width="1.35" stroke-linecap="round" stroke-linejoin="round"></path>
+    </svg>
+  `;
+}
+
+export function renderCheckIcon(className = "") {
+  return `
+    <svg class="${cx("board-inline-icon", className)}" aria-hidden="true" viewBox="0 0 16 16" fill="none">
+      <path d="M3.5 8.4L6.4 11.1L12.5 4.9" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"></path>
+    </svg>
+  `;
+}
+
 export function readStatusLabel(rawStatus) {
   if (typeof rawStatus !== "string" || rawStatus.trim().length === 0) {
     return "Unknown";

package/src/board/assets/runtime/clipboard.js

@@ -0,0 +1,34 @@
+export async function copyTextToClipboard(value) {
+  const text = typeof value === "string" ? value : String(value ?? "");
+
+  if (!text) {
+    throw new Error("Clipboard text is empty.");
+  }
+
+  if (navigator?.clipboard?.writeText) {
+    await navigator.clipboard.writeText(text);
+    return;
+  }
+
+  const textarea = document.createElement("textarea");
+  textarea.value = text;
+  textarea.setAttribute("readonly", "true");
+  textarea.setAttribute("aria-hidden", "true");
+  textarea.style.position = "fixed";
+  textarea.style.top = "0";
+  textarea.style.left = "0";
+  textarea.style.opacity = "0";
+  textarea.style.pointerEvents = "none";
+
+  document.body.append(textarea);
+  textarea.focus({ preventScroll: true });
+  textarea.select();
+  textarea.setSelectionRange(0, text.length);
+
+  const didCopy = document.execCommand("copy");
+  textarea.remove();
+
+  if (!didCopy) {
+    throw new Error("Clipboard API unavailable.");
+  }
+}

package/src/board/assets/runtime/delegation.js

@@ -43,6 +43,12 @@ export function createDelegation(rootElement, actions) {
       return;
     }
 
+    const copyEpicIdEl = target.closest("[data-copy-epic-id]");
+    if (copyEpicIdEl) {
+      actions.copyEpicId(copyEpicIdEl.dataset.copyEpicId || null);
+      return;
+    }
+
     // -- Backdrop-style close handlers ----------------------------------------
     // Only close when the click lands directly on the backdrop element itself,
     // not on any child content rendered inside the overlay.
@@ -242,6 +248,31 @@ export function createDelegation(rootElement, actions) {
     actions.handleKeydown(event);
   }
 
+  function handleDelegatedKeydown(event) {
+    if (event.defaultPrevented) {
+      return;
+    }
+
+    const target = event.target instanceof Element ? event.target : null;
+    if (!target) {
+      return;
+    }
+
+    if (target.closest("[data-copy-epic-id]")) {
+      return;
+    }
+
+    const openEpicEl = target.closest("[data-open-epic]");
+    if (!openEpicEl) {
+      return;
+    }
+
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      actions.openEpic(openEpicEl.dataset.openEpic || null);
+    }
+  }
+
   // ---------------------------------------------------------------------------
   // Drag-and-drop delegation
   // ---------------------------------------------------------------------------
@@ -291,6 +322,7 @@ export function createDelegation(rootElement, actions) {
   rootElement.addEventListener("dragstart", handleDragstart);
   rootElement.addEventListener("dragover", handleDragover);
   rootElement.addEventListener("drop", handleDrop);
+  rootElement.addEventListener("keydown", handleDelegatedKeydown);
   window.addEventListener("keydown", handleKeydown);
 
   // ---------------------------------------------------------------------------
@@ -304,6 +336,7 @@ export function createDelegation(rootElement, actions) {
     rootElement.removeEventListener("dragstart", handleDragstart);
     rootElement.removeEventListener("dragover", handleDragover);
     rootElement.removeEventListener("drop", handleDrop);
+    rootElement.removeEventListener("keydown", handleDelegatedKeydown);
     window.removeEventListener("keydown", handleKeydown);
   };
 }

package/src/board/assets/state/actions.js

@@ -1,3 +1,4 @@
+import { copyTextToClipboard } from "../runtime/clipboard.js";
 import { orderEpicsNewestFirst } from "./store.js";
 
 function cloneSnapshot(snapshot) {
@@ -156,6 +157,7 @@ export function createBoardActions(options) {
 
   let searchTimer = null;
   let pendingSearchValue = null;
+  let copyFeedbackTimer = null;
 
   const syncSearchInputToState = () => {
     const input = document.querySelector("#board-search-input");
@@ -186,6 +188,38 @@ export function createBoardActions(options) {
 
   const shouldRefocusSearchInput = () => document.activeElement?.id === "board-search-input";
 
+  const clearCopyFeedback = ({ rerenderBoard = true } = {}) => {
+    if (copyFeedbackTimer !== null) {
+      clearTimeout(copyFeedbackTimer);
+      copyFeedbackTimer = null;
+    }
+
+    if (!store.copyFeedback) {
+      return;
+    }
+
+    store.copyFeedback = null;
+    if (rerenderBoard) {
+      rerender();
+    }
+  };
+
+  const scheduleCopyFeedbackClear = (epicId) => {
+    if (copyFeedbackTimer !== null) {
+      clearTimeout(copyFeedbackTimer);
+    }
+
+    copyFeedbackTimer = setTimeout(() => {
+      copyFeedbackTimer = null;
+      if (store.copyFeedback?.epicId !== epicId) {
+        return;
+      }
+
+      store.copyFeedback = null;
+      rerender();
+    }, 1800);
+  };
+
   const commitSearch = (nextSearch, options = {}) => {
     const { focusInput = false } = options;
     cancelPendingSearch({ syncInput: false });
@@ -266,6 +300,37 @@ export function createBoardActions(options) {
     setView(view) {
       transition({ view });
     },
+    async copyEpicId(epicId) {
+      const normalizedEpicId = typeof epicId === "string" ? epicId.trim() : "";
+
+      if (!normalizedEpicId) {
+        clearCopyFeedback({ rerenderBoard: false });
+        store.notice = {
+          type: "error",
+          title: "Copy failed",
+          message: "Epic UUID is unavailable.",
+        };
+        rerender();
+        return;
+      }
+
+      try {
+        await copyTextToClipboard(normalizedEpicId);
+        store.copyFeedback = {
+          epicId: normalizedEpicId,
+        };
+        scheduleCopyFeedbackClear(normalizedEpicId);
+      } catch {
+        clearCopyFeedback({ rerenderBoard: false });
+        store.notice = {
+          type: "error",
+          title: "Copy failed",
+          message: "Could not copy the epic UUID.",
+        };
+      }
+
+      rerender();
+    },
     selectTask(taskId) {
       const task = getTaskById(taskId);
       if (!task) {
@@ -409,6 +474,9 @@ export function createBoardActions(options) {
         } else if (boardState.screen === "tasks") {
           event.preventDefault();
           this.showEpics();
+        } else if (store.copyFeedback) {
+          event.preventDefault();
+          clearCopyFeedback();
         } else if (store.notice) {
           event.preventDefault();
           store.notice = null;

package/src/board/assets/state/store.js

@@ -283,6 +283,7 @@ export function createStore(initialSnapshot, options = {}) {
     selectedSubtaskId: null,
     theme: readThemePreference(),
     focusedEpicIndex: 0,
+    copyFeedback: null,
     notice: null,
     isMutating: false,
     notesPanelOpen: storedState.notesPanelOpen === true,