Add project documentation

Include design system guidelines, Phase 3 roadmap, code quality
review, proposed README, and authentication ADR.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

1 files changed, 51 insertions, 0 deletions

diff --git a/docs/PHASE_3_PLAN.md b/docs/PHASE_3_PLAN.md
new file mode 100644
index 0000000..61bac30
--- /dev/null
+++ b/docs/PHASE_3_PLAN.md
@@ -0,0 +1,51 @@
+# Phase 3: Interactivity & Write Operations
+
+**Goal:** Transform the dashboard from a passive read-only viewer into an active command center where users can manage tasks directly.
+
+## Architectural Alignment
+The `internal/api/interfaces.go` file already defines the necessary write contracts (`CreateCard`, `UpdateCard`, `CreateTask`, `CompleteTask`). Phase 3 focuses on implementing these methods and wiring them to the UI.
+
+## Step 1: Trello Write Operations (Priority)
+**Objective:** Enable basic card management within the dashboard.
+
+*   **Backend (`internal/api/trello.go`):**
+    *   Implement `CreateCard(title, listID string) error`
+    *   Implement `UpdateCard(cardID string, updates map[string]interface{}) error` (for moving lists or archiving)
+*   **Handlers (`internal/handlers/trello.go`):**
+    *   `HandleCreateCard`: Accepts POST data, calls API, returns updated list HTML.
+    *   `HandleMoveCard`: Accepts POST data (new list ID), calls API.
+    *   `HandleCompleteCard`: Archives card or moves to "Done" list.
+*   **UI (`web/templates/partials/trello-boards.html`):**
+    *   **Add Card:** Simple input + button at the bottom of each list (`hx-post`).
+    *   **Complete:** Checkbox or "Done" button on cards.
+    *   **Drag & Drop:** (Optional for v1) Use `SortableJS` wired to `hx-post` for list changes.
+
+## Step 2: Todoist Write Operations
+**Objective:** Quick task capture and completion.
+
+*   **Backend (`internal/api/todoist.go`):**
+    *   Implement `CreateTask(content string) error`
+    *   Implement `CompleteTask(taskID string) error`
+*   **Handlers (`internal/handlers/todoist.go`):**
+    *   `HandleCreateTask`: Adds task, returns updated list.
+    *   `HandleCompleteTask`: Marks complete, returns updated list (or empty response to remove element).
+*   **UI (`web/templates/partials/tasks-tab.html`):**
+    *   **Quick Add:** Input field at top of list (`hx-post`, `hx-target="#task-list"`, `hx-swap="prepend"`).
+    *   **Completion:** Checkbox on task items (`hx-post`, `hx-target="closest li"`, `hx-swap="delete"`).
+
+## Step 3: Unified "Quick Add" (Power User Feature)
+**Objective:** A single entry point for all tasks.
+
+*   **Concept:** Global input bar (e.g., triggered by `CMD+K` or always visible).
+*   **Logic:**
+    *   Parses input text for keywords/tags.
+    *   `"Buy milk #groceries"` -> Routes to Todoist.
+    *   `"Fix bug #work"` -> Routes to Trello.
+    *   `"Idea: New app"` -> Routes to Obsidian (Append to Daily Note - *Future Scope*).
+*   **Implementation:**
+    *   `HandleQuickAdd`: Parses string, delegates to appropriate Service, returns success toast.
+
+## Technical Strategy
+*   **HTMX:** Use `hx-post`, `hx-target`, and `hx-swap` for seamless updates.
+*   **Optimistic UI:** Where possible, remove/add items from DOM immediately while request processes (using HTMX `hx-on` or CSS transitions).
+*   **Error Handling:** If API call fails, revert UI state and show `error-banner`.