docs/features.md
Rama main · réplica de lectura del repositorio original.
```
╔════════════════════════════════════════════════════════════════════════════╗
║ ║
║ FEATURES ║
║ Every major capability in Cloud Codex, in one read. ║
║ ║
╚════════════════════════════════════════════════════════════════════════════╝
```
# Features
Cloud Codex is built around six pillars. Everything in this document is one of
the supporting features that makes one of them work.
```
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ CLOUD CODEX ┃
┗━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┛
│
┌──────────┬────────┬───────┴──────┬──────────┬──────────┐
│ │ │ │ │ │
real-time GitHub layered comments & notifications self-host
CRDT 1st-class access annotations + activity in one box
```
---
## Real-Time Collaborative Editing
Multiple users can edit the same document simultaneously. Changes are merged
automatically using **Yjs CRDTs** (Conflict-free Replicated Data Types),
ensuring every user sees a consistent view without manual conflict resolution.
Remote cursors and text selections render in real time so collaborators can see
exactly where others are working.
---
## Presence Awareness
Live presence indicators show which users are currently viewing or editing each
log. Avatar badges appear throughout the interface — in the log tree sidebar,
the editor toolbar, the top navigation bar, and the explore/browse view —
giving squads immediate visibility into who is active. A dedicated presence
API exposes per-log editing sessions for integration across views.
---
## Rich Text & Markdown Editing
Documents can be authored in either a full WYSIWYG rich text editor (powered
by Tiptap) or a Markdown source editor with a live rendered preview. Users
switch between modes at any time, and their preference is saved across
sessions.
---
## Code Syntax Highlighting
Fenced code blocks support syntax highlighting for **25 languages**
(JavaScript, TypeScript, Python, Java, C, C++, Go, Rust, Ruby, PHP, SQL, HTML,
CSS, JSON, YAML, Bash, and more). A language selector dropdown is built into
each code block, with auto-detection as a fallback. Highlighting renders in
both the editor and read-only views.
---
## Draw.io Diagram Integration
Users can embed draw.io (diagrams.net) diagrams directly into documents.
Clicking the toolbar button opens the draw.io editor in a popup. Diagram XML
and a rendered SVG preview are stored inline in the document, and the diagram
can be re-opened, edited, or removed at any time via the embed API.
---
## Resizable Images
Images inserted into documents can be interactively resized using drag handles.
The width is persisted in the document HTML so the layout is preserved for all
viewers. An image crop modal with an eight-handle crop rectangle, rule-of-
thirds grid overlay, and canvas-based output is available when inserting
images.
---
## Document Image Hosting
Images pasted or dropped into the editor are automatically uploaded, processed
(resized to a maximum of 2048 px, converted to WebP at 85 % quality), and
served from a dedicated static endpoint with 30-day cache headers.
Content-hash deduplication (SHA-256) prevents storing the same image twice.
Base64 data URIs are extracted on save and re-inlined for self-contained
exports.
---
## Inline Comments & Annotations
Squad members can highlight text and attach comments anchored to specific
passages. Comments support a **tag system** (comment, suggestion, question,
issue, note) and a **status workflow** (open → resolved / dismissed). Threaded
replies enable focused discussions, and all comment activity is broadcast in
real time via WebSocket.
---
## @Mentions
Typing `@` inside the editor opens an autocomplete that surfaces squad members
the user has visibility into. Posting a document with a fresh mention does
two things automatically: it sends the mentioned user a notification (in-app
+ email if their preferences allow it) and **adds them as a watcher** on the
document so they keep getting updates without having to opt in manually.
---
## Document Watches & Subscriptions
A user can **watch** a log or an entire archive to be notified about future
activity (new comments, edits, published versions). Watches are explicit
(toggled from the document UI) or implicit (added automatically when the user
is mentioned or replies to a comment). The notification subsystem fans
activity out to all watchers, applying the 60-second coalescing window so
a flurry of edits does not produce a flurry of inbox entries.
See [notifications.md](./notifications.md) for the underlying mechanics.
---
## Notifications Inbox
A unified inbox surfaces every alert: mentions, comments on watched docs,
new versions on watched docs, squad invitations, and watched-archive activity.
Each notification persists in the database, pushes to the user's open tabs
over a dedicated WebSocket (`/notifications-ws`), and may also send an email
based on per-type preferences. A bell icon with an unread badge sits in the
top navigation bar; the full inbox is at `/notifications`.
---
## Notification Preferences
Per-type **email** opt-in/out lives at `/notifications/preferences`. Defaults
favor the alerts users typically want (mentions, comments on their docs,
watched-doc comments, watched publishes, squad invites) and disable the
chattier ones (every watched-doc edit). In-app inbox delivery is always on —
preferences only control the email channel.
---
## Workspace Activity Stream
A scrollable, filterable feed of meaningful events in a workspace: documents
created/published/restored, comments added/resolved, archive grants changed,
squad memberships moved. The feed is **access-filtered at query time** through
the same ownership SQL fragments the rest of the app uses, so a user only
sees activity on resources they can read. Backed by the `activity_log` table,
which is auto-pruned daily to a 365-day window.
---
## Workspaces & Squads
Content is organized under workspaces, each managed by a single owner. Within
a workspace, **squads** group users with role-based membership (member, admin,
owner). Squad invitations track pending, accepted, and declined states.
Granular per-member permissions control read, write, log creation, archive
creation, member management, version deletion, and publishing rights.
---
## Archives & Layered Access Control
Archives serve as top-level containers for related logs and can optionally be
scoped to a specific squad. Logs are arranged in a hierarchical parent-child
tree structure with breadcrumb navigation. Access is **layered** — the system
walks a 7-step priority cascade on every check:
```
1. super admin ─► allow
2. user ID listed in archives.read_access ─► allow
3. archive creator (archives.created_by) ─► allow
4. workspace owner (squad → workspaces.owner_id = id) ─► allow
5. squad member with role='owner' or matching can_* ─► allow
6. user is in any squad listed in read_access_squads ─► allow
7. read_access_workspace=TRUE and any squad in workspace ─► allow
─► deny
```
A collapsible access panel on each archive card displays the owner, inherited
squad members with role and permission badges, workspace-level grants,
explicitly granted squads, and individually granted users. Users whose access
is already covered by a squad or owner membership are omitted from the
individual user list to keep the display clean.
See [access-control.md](./access-control.md) for the full resolution logic.
---
## GitHub Integration
Archives can be linked to GitHub repositories for browsing, editing, and pull
request management without leaving the platform. The integration is a
**live API proxy** — no webhooks, no background sync. Features include:
- Repository search, file tree navigation, and file viewing with smart
text-file filtering (50+ supported extensions)
- In-browser file editing with commit support (create and update files via
the GitHub Contents API)
- Branch management (list and create branches from any ref)
- Pull request listing, creation, commits, and changed-files view
- Encrypted access token storage (AES-256-GCM derived from the client secret
via scrypt)
- CI/check-run status surfaced inline (Actions runs, check-runs per SHA)
- Releases listing and creation
---
## GitHub PR Merge Workflow
Cloud Codex maintains a **PR session** for each pull request the team is
working in (`github_pr_sessions`). The merge dialog tracks files changed,
in-thread comments, code reviews, and the diff state across the lifetime of
the PR. Comments and reviews can be posted from inside the doc tool, with the
session linking PR conversation back to any documents tied to the touched
files.
---
## GitHub Code, Issue & PR Embeds
`/github/embed/code` and the issue search endpoints feed embedded blocks
that the editor can pin into a document (`github_embed_refs` records the
pinned `ref`/`SHA` so the embed stays stable even if the underlying file
moves). Embeds render with their current state when the document is opened —
they're not snapshots; they're live references that show pinned content with
a pointer to "see the current version on GitHub".
---
## Archive ↔ Repository Linking
An archive can be **bulk-linked** to a repository's `docs/` path. Cloud Codex
imports every supported file as a log, preserving folder structure as the
log tree. From there each imported log is individually linked back to its
source file, and the per-doc pull/push/resolve workflow keeps both sides in
sync. Refresh imports new files added since the last import; existing
linked files are left alone.
---
## OAuth & Single Sign-On
**Google Workspace SSO** enables domain-restricted login with automatic account
creation for allowed domains. **GitHub OAuth** provides account linking and
access token exchange used by the GitHub integration. Both providers support
unlinking flows with lockout prevention, and a provider detection endpoint
drives a dynamic login UI.
---
## Admin Console
A dedicated admin dashboard provides platform-wide management:
- **Statistics** — live counts of users, workspaces, squads, archives, logs,
and pending invitations.
- **Workspace management** — create workspaces (with optional squad and
archive scaffolding), list, and delete.
- **User management** — list all users with squad membership counts, delete
non-admin accounts, toggle admin status, edit per-user creation
permissions.
- **User invitations** — invite users by email (sends a branded HTML signup
link), optionally pre-assign a squad and role so the new account joins it
automatically on signup instead of landing in the app with no squad, list
pending invitations, and revoke.
- **Live presence telemetry** — see which documents are currently being
edited and by whom.
- **Outbound webhooks** — tell a receiver about document and archive changes,
and see when one has stalled and why (Admin, then Webhooks;
[api/admin.md](api/admin.md#webhooks)).
An admin super-user is automatically synced from environment variables on
server startup.
---
## Explore & Browse Documents
A card-based browse view lists all accessible documents with sorting (newest,
oldest, title, archive), paginated results, and integrated search with
contextual match snippets and keyword highlighting. Each card shows the
archive name, author, date, word count, and live presence avatars indicating
who is currently editing.
---
## Version History
Any authorized user can publish a named version snapshot with optional
release notes (up to 5,000 characters). The version browser lets users browse,
preview, and compare historical snapshots. Previous versions can be restored
at any time, with all content re-sanitized on restoration.
---
## Document Import & Export
Logs can be created by uploading HTML, Markdown, plain text, PDF, or Word
DOCX files. All imported formats are automatically converted to sanitized
HTML. Logs can be exported as DOCX, HTML, Markdown, plain text, or PDF (via
browser print-to-PDF).
---
## Full-Text Search
Search is powered by a MySQL `FULLTEXT` index across log titles and
plain-text content. Results are scoped to logs the current user has
permission to access and are returned with paginated snippet previews.
---
## Favorites
Users can star any document to add it to their personal favorites list. A
star toggle appears in the editor header on every document. The home page
displays a dedicated favorites section above the browse view, showing the
most recently favorited documents as cards with title, archive, author, and
excerpt. Favorites are scoped per-user and persist across sessions.
---
## User Profiles & Preferences
Users can upload a profile picture (automatically resized to 256 × 256 WebP),
update their name, email, and password, and customize appearance preferences
including accent color, editor font size, and default editor mode. Density and the sidebar
default were removed (W6-CDX-42); a value an earlier build stored is dropped on load.
An account that signs in through an OIDC issuer keeps its own name, email, password and two-factor in
Codex: the Account page edits them like any other account. The two-factor panel says that sign-in is managed by
the issuer when the account's session came through it.
---
## Authentication & Two-Factor Security
Authentication uses 64-character cryptographically random session tokens with
a 7-day expiry, one per sign-in so each device signs in and out on its own,
stored only as a SHA-256 digest. Password reset is handled via email-based token flow.
Two-factor authentication supports both **email OTP codes** and **TOTP
authenticator apps** (with QR code setup).
---
## Guided Onboarding
A first-run welcome shows every user, admin included, what they already have
rather than making them create anything: their squad (if any), an archive
they can read, and a document to start in, teaching the
workspace/squad/archive/document hierarchy by pointing at a live instance of
it. A user with no squad yet sees a count of pending squad invitations, if
any, instead. It shows once, the first time a user is authenticated after
account creation (or, for the admin, after the instance first boots), and is
dismissed permanently once seen. An admin invitation can now optionally
pre-assign a squad and role, so a newly invited user has something to see
here immediately instead of landing with nothing.