# User Stories — Outline Sync Web UI
**Derived from:** WEBUI_PRD.md v2.0
**Date:** 2026-03-07

Each story follows the format: **As a [user], I want [goal] so that [benefit].**
Acceptance criteria map directly to automated test IDs in the corresponding `test_phase_*.py` files.

---

## Phase A — WebDAV Container

**US-A1** — As a user with Obsidian running locally, I want my vault files to sync automatically to the VPS via WebDAV, so that I do not need terminal access for file transfer.
- AC: A file created in the vault directory is retrievable via WebDAV GET within the sync interval.
- AC: A file updated locally appears updated on the WebDAV server after sync.
- AC: Deleted files are removed from the WebDAV share.
- Tests: `test_phase_a_webdav.py::TestWebDAVFileOps`

**US-A2** — As a system administrator, I want the WebDAV endpoint protected by basic auth and Tailscale network isolation, so that the vault is not publicly accessible.
- AC: Unauthenticated requests return 401.
- AC: Requests with valid credentials return 200.
- AC: The WebDAV port is not bound to the public interface.
- Tests: `test_phase_a_webdav.py::TestWebDAVAuth`

**US-A3** — As a user, I want the `.git/` directory excluded from WebDAV access, so that git internals are not exposed or corrupted by Obsidian.
- AC: GET request to `/.git/` returns 403 or 404.
- AC: Obsidian plugin cannot overwrite `.git/` files via WebDAV.
- Tests: `test_phase_a_webdav.py::TestWebDAVGitProtection`

**US-A4** — As an Obsidian user, I want WebDAV to support bidirectional file sync (upload, download, delete), so that both push and pull directions work without manual steps.
- AC: PROPFIND returns correct file listing.
- AC: PUT creates/updates files.
- AC: DELETE removes files.
- Tests: `test_phase_a_webdav.py::TestWebDAVMethods`

---

## Phase B — Read-Only Dashboard

**US-B1** — As a user, I want to open `https://sync.domverse.de` and immediately see the current vault state, so that I know if anything needs attention before syncing.
- AC: GET `/` returns HTTP 200 with HTML content.
- AC: Page contains vault status badge (Clean / Dirty / Conflicts).
- AC: Page shows count of pending local changes.
- Tests: `test_phase_b_dashboard.py::TestDashboardPage`

**US-B2** — As a user, I want to see when the vault was last pulled from Outline and last pushed to Outline, so that I can judge how stale my local state is.
- AC: GET `/status` returns JSON with `last_pull`, `last_push` timestamps.
- AC: Dashboard renders these timestamps in human-readable form.
- Tests: `test_phase_b_dashboard.py::TestStatusEndpoint`

**US-B3** — As a user, I want the dashboard to show a conflict warning badge when git merge conflicts are present, so that I do not accidentally push broken files.
- AC: When conflict files exist, `/status` includes `conflicts: N` where N > 0.
- AC: Dashboard shows warning banner with link to `/conflicts`.
- Tests: `test_phase_b_dashboard.py::TestConflictBadge`

**US-B4** — As a user, I want the dashboard to show how many files Obsidian has written via WebDAV that are not yet pushed to Outline, so that I know the push button's scope.
- AC: Pending count = `git diff outline..main --name-only | wc -l`.
- AC: Count updates on each page load without manual refresh.
- Tests: `test_phase_b_dashboard.py::TestPendingCount`

---

## Phase C — Pull with Live Output

**US-C1** — As a user, I want to click "Get from Outline" and see live streaming output in the browser, so that I can monitor progress without terminal access.
- AC: POST `/pull` responds immediately with a `job_id`.
- AC: GET `/stream/{job_id}` returns `text/event-stream` content type.
- AC: SSE stream emits at least one `data:` event per document processed.
- AC: Stream ends with a `done` event containing a summary.
- Tests: `test_phase_c_pull.py::TestPullStreaming`

**US-C2** — As a user, I want the pull to fetch new Outline documents and update them in the vault, so that Obsidian shows the latest wiki content.
- AC: After pull, new documents appear as `.md` files in the vault.
- AC: Modified documents have updated content.
- AC: The `outline` branch is advanced to reflect the new Outline state.
- Tests: `test_phase_c_pull.py::TestPullContent`

**US-C3** — As a user, I want the pull operation to be idempotent when nothing changed in Outline, so that repeated pulls are safe and fast.
- AC: Pull with no Outline changes returns success with "0 changes" summary.
- AC: No git commits are made when there are no changes.
- Tests: `test_phase_c_pull.py::TestPullIdempotent`

**US-C4** — As a user, I want only one sync job running at a time, so that concurrent pull/push operations do not corrupt the vault.
- AC: Starting a pull while one is in progress returns HTTP 409 Conflict.
- AC: Job lock is released when the stream closes (done or error).
- Tests: `test_phase_c_pull.py::TestJobLock`

---

## Phase D — Pending Changes View

**US-D1** — As a user, I want to see a structured list of pending changes before pushing, so that I can review what will be sent to Outline.
- AC: GET `/changes` returns 200 with a list of change objects.
- AC: Each item has a `path`, `status` (modified/added/renamed/deleted) and `action` (what the sync engine will do).
- Tests: `test_phase_d_changes.py::TestChangesEndpoint`

**US-D2** — As a user, I want modified files listed separately from new files and deleted files, so that I understand the scope of each change type.
- AC: `status=modified` for files changed since last outline branch commit.
- AC: `status=added` for files not on the outline branch at all.
- AC: `status=deleted` for files removed from main but still on outline.
- AC: `status=renamed` with both `from` and `to` paths.
- Tests: `test_phase_d_changes.py::TestChangeCategories`

**US-D3** — As a user, I want to preview the diff for a modified file inline, so that I can confirm the content before pushing.
- AC: GET `/diff/{encoded_path}` returns an HTML fragment with two columns.
- AC: Left column shows the outline branch version, right shows main branch version.
- AC: Added lines are highlighted green, removed lines red.
- Tests: `test_phase_d_changes.py::TestDiffPreview`

**US-D4** — As a user, I want deleted files shown as "skipped" when deletions are disabled in settings, so that I know why they are not being removed from Outline.
- AC: When `allow_deletions=false`, deleted files appear with `action=skip`.
- AC: Reason text explains deletions are disabled.
- Tests: `test_phase_d_changes.py::TestDeletedFilesSkipped`

---

## Phase E — Push with Live Output

**US-E1** — As a user, I want to click "Send to Outline" and see live streaming output, so that I can monitor progress for each file.
- AC: POST `/push` returns a `job_id`.
- AC: SSE stream emits one event per file with status (created/updated/skipped/error).
- AC: Final event contains summary counts (created, updated, skipped, errors).
- Tests: `test_phase_e_push.py::TestPushStreaming`

**US-E2** — As a user, I want new Obsidian files to appear in Outline under the correct collection and parent, so that the hierarchy is preserved.
- AC: A file `Projekte/NewNote.md` (no frontmatter) is created in Outline under the "Projekte" collection.
- AC: After push, the file receives frontmatter with `outline_id`.
- AC: The updated file is committed and becomes readable via WebDAV.
- Tests: `test_phase_e_push.py::TestNewFileCreation`

**US-E3** — As a user, I want push to be blocked when there are unresolved conflicts, so that I cannot push broken files with conflict markers.
- AC: When `git ls-files -u` returns conflict files, POST `/push` returns HTTP 409.
- AC: Response body includes list of conflicting paths.
- Tests: `test_phase_e_push.py::TestPushBlockedByConflicts`

**US-E4** — As a user, I want a new top-level folder in Obsidian to create a new Outline collection automatically, so that new categories do not require manual Outline setup.
- AC: Folder `NewCollection/` not mapped to any existing collection → `collections.create` called.
- AC: Documents inside the new folder are created under the new collection.
- Tests: `test_phase_e_push.py::TestNewCollectionCreation`

**US-E5** — As a user, I want the push to handle renames (file moved/title changed) without deleting and recreating the document, so that Outline document history and URL are preserved.
- AC: Renamed file detected via git rename detection.
- AC: Outline `documents.update` called (not delete+create).
- Tests: `test_phase_e_push.py::TestRenameHandling`

---

## Phase F — Conflict Resolution

**US-F1** — As a user, I want to see all version conflicts listed in the browser, so that I can resolve them without using git on the command line.
- AC: GET `/conflicts` returns list of conflict file paths.
- AC: Each item includes local timestamp and Outline edit timestamp.
- Tests: `test_phase_f_conflicts.py::TestConflictsList`

**US-F2** — As a user, I want a side-by-side diff view per conflicting file, so that I can compare my Obsidian edit with the Outline edit before choosing.
- AC: GET `/diff/{encoded_path}` for a conflict file returns two-column HTML diff.
- AC: Diff is rendered using Python `difflib` or equivalent.
- Tests: `test_phase_f_conflicts.py::TestConflictDiff`

**US-F3** — As a user, I want to click "Keep mine" to accept my local Obsidian edit, so that my changes win.
- AC: POST `/resolve` with `{file: "path", accept: "local"}` resolves conflict in favour of local.
- AC: Conflict markers are removed from the file.
- AC: File is committed to main branch.
- Tests: `test_phase_f_conflicts.py::TestResolveLocal`

**US-F4** — As a user, I want to click "Keep Outline's" to accept the Outline version, so that the wiki state wins.
- AC: POST `/resolve` with `{file: "path", accept: "remote"}` resolves in favour of outline branch.
- AC: Conflict markers are removed.
- AC: File is committed to main branch.
- Tests: `test_phase_f_conflicts.py::TestResolveRemote`

**US-F5** — As a user, I want the system to reject invalid file paths in resolve requests, so that an attacker cannot trigger arbitrary git operations via the UI.
- AC: `/resolve` with a path not in the conflict list returns HTTP 422.
- AC: Path traversal attempts (`../`) return HTTP 422.
- Tests: `test_phase_f_conflicts.py::TestResolveValidation`

**US-F6** — As a user, I want to be redirected to the dashboard after resolving all conflicts, with "Push now available" displayed, so that the workflow continues naturally.
- AC: After last conflict resolved, GET `/conflicts` returns empty list.
- AC: Dashboard status badge updates to show clean/push-ready state.
- Tests: `test_phase_f_conflicts.py::TestAllConflictsResolved`

---

## Phase G — Sync History

**US-G1** — As a user, I want to view a chronological history of all sync operations, so that I can audit what changed and when.
- AC: GET `/history` returns HTTP 200 with HTML content.
- AC: Sync entries are shown in reverse chronological order.
- AC: Each entry shows: timestamp, direction (pull/push), files affected, status.
- Tests: `test_phase_g_history.py::TestHistoryPage`

**US-G2** — As a user, I want the history sourced from `_sync_log.md`, so that it remains readable as a plain Obsidian note.
- AC: `_sync_log.md` in vault root is parsed into structured records.
- AC: Entries are displayed as an HTML table, not raw markdown.
- Tests: `test_phase_g_history.py::TestSyncLogParsing`

---

## End-to-End Flows

**US-E2E1** — As a user, I want the full Obsidian → Outline flow to work without terminal access.
- Tests: `test_e2e.py::TestObsidianToOutlineFlow`

**US-E2E2** — As a user, I want the full Outline → Obsidian flow to work without terminal access.
- Tests: `test_e2e.py::TestOutlineToObsidianFlow`

**US-E2E3** — As a user, I want conflicts detected and resolvable end-to-end through the browser.
- Tests: `test_e2e.py::TestConflictResolutionFlow`

**US-E2E4** — As a user, I want a new file created in Obsidian to reach Outline with correct hierarchy, frontmatter written back, and the ID visible in Obsidian on the next sync.
- Tests: `test_e2e.py::TestNewFileRoundTrip`