forked from mirror/crumbs-original
Frederic CabassutandClaude Opus 5
4812eaf1ed
Issue #77 was caused by these docs. FEATURES.md promised "Reset passwords for any user" when no such control existed, so a user reasonably filed a bug against a promise the software never made. The docs were describing the API surface, not the UI. Now that the control ships, they describe what it actually does — and the same audit turned up three neighbouring claims that were already wrong. Corrected: - "Reset passwords for any user" — it is any user other than yourself, whose account signs in with a password, and Crumbs generates the password and shows it once rather than the admin choosing one. - "Revoke all sessions ... for any user" — Revoke has always been self-excluded in the UI. Wrong before this feature existed. - The AUTH.md sentence covering both capabilities in one breath, so fixing only the reset half would have left the revoke half wrong. - Two references to a "Settings > Users > Invite User" affordance that does not exist; the section is headed Create User. Same defect as #77 — documentation promising UI that was never built — one of them buried in the Authentik setup guide. Newly documented, all previously silent: - The sole-admin dead end, and its bound. There is no forgot-password flow, the reset control excludes your own row, and Profile requires your current password. Another admin can reset you. Failing that, an OAuth sign-in recovers the account when a provider is configured and the email matches — at the cost of handing the account to that provider permanently. Only with no second admin and no provider is there genuinely no way back in through the app. An earlier draft stated that absolutely, which would have pushed an operator toward restoring from backup when one OAuth sign-in would have done. - The OAuth pre-link trap: a password set during invite works only until the first OAuth sign-in, which hands the account to the provider. Ticking OAuth-only avoids the surprise. Tracked for a real fix in #78. - That the reset notification is best-effort. Both layers swallow send errors, so a successful reset is not evidence the user was told. - That a displayed password is only good until that account's password changes again, by any route, with nothing marking it stale. - That an unconfirmed reset shows the password anyway, and that one should be kept and retried. - That the control is also unavailable while a password is on screen — the one unavailable state that shows no reason, so an admin meeting a dead button has somewhere to look. No openapi.yaml or API.md change: neither documents /api/admin/* at all, so the new 400 needs no spec edit and pnpm docs:api regenerates nothing relevant. That gap predates this work. Verified: pnpm check 0 errors / 14 pre-existing warnings. Every factual claim traced to code by the author and again by an independent reviewer, which is how the false recovery claim was caught. Reviewed-by: adversarial-review (13 of 14 claims verified true on the first pass; failed for one false absolute, since bounded) Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RbqJcFofZSbhbGwUwZP3wU
7.4 KiB
7.4 KiB
Features
Core Features (MVP)
Notes CRUD
- Create, read, update, and delete notes
- Notes have a title and content body
- Content supports full Markdown syntax
- Auto-save on editor close
Rich Text Editor
- WYSIWYG editing powered by Tiptap
- Formatting toolbar with visual controls
- Raw Markdown mode toggle for direct editing
- Undo/Redo with keyboard shortcuts
Text Formatting
- Bold (
**text**/ Ctrl+B) - Italic (
*text*/ Ctrl+I) - Underline (Ctrl+U)
Strikethrough(~~text~~/ Ctrl+Shift+X)- Headings (
# H1through###### H6) - Blockquotes (
> quote) - Unordered lists (
- item) - Ordered lists (
1. item) - Code blocks (triple backtick)
- Inline code (single backtick)
- Links — insert, edit, and remove with URL input
- Tables (insert, add/delete rows and columns)
- Dividers (horizontal rules)
- Text alignment (left, center, right, justify)
- Line breaks
Checklists / Task Lists
- Toggle between regular note and checklist mode
- Add, remove, reorder checklist items
- Check/uncheck items with checkboxes
- Checked items get strikethrough styling
- Enter key adds new item, Backspace removes empty items
- Nested checklists: single-level nesting for sub-tasks
- Tab / Shift+Tab to indent or outdent an item (keyboard)
- Drag handle horizontal swipe for mobile indentation
- Checking a parent item checks all its children
- Done section groups checked children under their parent label
Image Attachments
- Upload images via file picker or drag-and-drop
- Supports JPEG, PNG, GIF, WebP, SVG
- Max file size: 10MB
- Client-side optimization: images resized to fit 1920×1920, compressed to WebP (~80% quality), transparent PNGs preserved
- Auto-generated thumbnails: 200×200 WebP at 60% quality for fast card previews
- Thumbnail strip on note cards (up to 3 images, "+N" badge for more)
- Full-size images in editor, thumbnails on cards (
&thumb=1) - Offline support: optimized blobs stored in IndexedDB, displayed via blob URLs, auto-synced on reconnect
- Pending upload indicator on offline-queued images
- Service worker CacheFirst caching for previously-viewed images
- Remove attachments from editor
Tag Organization
- Inline
#hashtagextraction from note content - Tags automatically parsed from title and content
- Filter notes by tag (sidebar + tag chips)
- Tags are case-insensitive and deduplicated
- Tags inside code blocks and URLs are ignored
Color-Coded Notes
12 note colors:
- Default, Coral, Peach, Sand, Mint, Sage
- Fog, Storm, Dusk, Blossom, Clay, Chalk
- Colors adapt to note theme
Dark Mode
- Three-way theme toggle: System / Light / Dark (in Settings > Preferences)
- Dark mode uses near-neutral warm ink surfaces (not a sepia-tinted parchment) — retro aesthetic preserved in both themes
- Respects system
prefers-color-schemepreference by default - FOUC-free: theme applied before first paint via a blocking inline script
Pin Notes
- Pin important notes to always appear at top
- Pinned section separated from unpinned notes
- Toggle pin from note card hover actions
Archive
- Archive notes to declutter main view
- Archived notes accessible from sidebar
- Unarchive to restore to main view
Trash
- Soft delete moves notes to trash
- Trash view accessible from sidebar
- Restore notes from trash
- Permanently delete from trash
Note Sharing / Collaboration
- Public link sharing: share any note via a public URL — no login required for viewers
- Toggle public link on/off from the share dialog
- Copy shareable URL with one click
- Read-only public page with full markdown/checklist/image rendering
- Public links are automatically invalidated when a note is trashed
- Rate-limited public endpoints (60 req/min per IP)
- Globe icon on note cards indicates a public link is active
- Share notes with other users on the same instance
- User search autocomplete for adding collaborators
- Full collaboration: both owner and collaborators can edit content, color, and checklist mode
- Per-user state: pin, archive, and sort order are independent per user
- Owner-only actions: trash, delete, share/unshare
- Sharing indicator on note cards (Globe for public, Users for collaborators-only)
- Hover popover showing sharing status and collaborator names
- Share dialog accessible from editor toolbar
- Collaborators can leave shared notes
- Shared notes appear mixed in main list alongside owned notes
- Email notifications (requires SMTP config, opt-out in preferences):
- Share notifications when a note is shared with you
- Welcome email when admin creates your account
- Password reset notification
- Account deletion confirmation
- Email address change notification
- Role change notification (admin/user)
- Removed from shared note notification
- Shared note permanently deleted notification
- Account locked alert (after failed login attempts)
Note Version History
- Browse previous versions of any note
- Versions are automatically saved when content changes
- Restore any previous version with one click
- Version snapshots are only created when content actually changes (not on metadata-only updates)
Full-Text Search
- Search across note titles, content, and tags
- Real-time search results as you type
- Clear search to restore original view
- Case-insensitive matching
Authentication & OAuth / SSO
- Multi-user with role-based access (admin / user)
- Password auth (Argon2) + optional OAuth/SSO (Google, GitHub, any OIDC provider)
- Session-based auth with active session management
- Invite-only OAuth model with PKCE-secured flows
- See AUTH.md for full details and provider setup guides
User Management (admin)
- Admin dashboard to create, list, and delete users
- Assign roles (admin / user)
- Reset another user's password — Crumbs generates a 20-character password and shows it once in that user's row, with a copy button; it cannot be shown again
- Only for accounts that sign in with a password — OAuth/SSO accounts show why the reset is unavailable
- Your own password is changed from Settings > Profile, not here
- A reset does not sign the user out — revoke their sessions separately to force a logout
- Revoke all sessions (force logout) for any user other than yourself
PWA / Offline-First
- Installable as standalone app
- Web app manifest with icons
- Service worker for asset caching (CacheFirst for attachments, NetworkFirst for API)
- IndexedDB for local data storage (notes + pending attachments)
- Background sync every 30 seconds (notes + offline attachments)
- LWW conflict resolution for multi-device use
- Sync status indicator (synced/syncing/offline/error)
MCP Server (Model Context Protocol)
- Built-in MCP endpoint at
POST /api/mcp(Streamable HTTP transport) - 14 tools: list, get, create, update, trash, restore, archive, unarchive, delete, search notes; list tags; pin, reorder notes; upload images
- API key authentication (Bearer token)
- Compatible with Claude Code, Claude Desktop, and other MCP clients
- Stateful sessions with automatic cleanup
API Key Management
- Generate API keys from the Settings page
- Keys use
crumbs_prefix for easy identification - SHA-256 hashed storage (keys shown once at creation)
- Track last-used timestamps
- Revoke keys with confirmation dialog
- MCP client config example shown in Settings
Docker Deployment
- Multi-stage Dockerfile (build + slim runtime)
- docker-compose.yml with persistent volume
- Health check endpoint
- Runs as non-root user
- Configurable via environment variables