Noma Cloud Guide

What Noma Cloud is for

Use Noma Cloud when a .noma document should move beyond a local HTML file:

• collaborate on a paper, research memo, book, or documentation space
• keep multiple pages inside one workspace
• give viewers and editors different access
• share stable page, artifact, and published-site links
• let an agent patch a named block without rewriting the whole source
• discuss and approve changes at a stable block or saved document version
• manage delivery work with projects, issues, boards, backlog, and sprints in the same space
• expose a permission-aware query API for future Codex plugins and automation

The source remains plain Noma. The cloud layer adds persistence, users, permissions, share links, site membership, rendered artifacts, and the database index around that source.

Technical preview boundaries

The v0.17 Cloud release is a self-hosted technical preview, not a managed multi-tenant SaaS or a completed enterprise integration suite:

• Ask Noma uses deterministic local hybrid retrieval and extractive source

summaries. It does not call a hosted LLM or claim generative-answer quality.

• Connector endpoints persist permission, URL, hash, timestamp, and tombstone

lineage. OAuth clients, provider polling, and background synchronization workers are deployment-specific follow-up work.

• Recipe runs produce reviewable plans with a proof_proposal_only policy.

There is no built-in scheduler or autonomous worker loop.

• OIDC/SAML and SCIM routes are trusted-proxy and provisioning contracts. The

reverse proxy or identity gateway performs protocol validation before sending a shared-secret assertion to Noma.

• Realtime collaboration is an ordered, pollable operation feed with atomic

hash preconditions. It is not a WebSocket presence, cursor, or CRDT system.

• Retention and legal-hold cleanup currently cover platform metadata records.

Canonical documents, immutable revisions, and SQLite backup retention remain explicit operator responsibilities.

These boundaries keep launch claims aligned with the implementation while the retrieval, proof, permission, and source-portability contracts are evaluated with real teams.

Run it locally

From a checkout:

npm install
npm run build:cloud
PORT=3000 npm start
open http://localhost:3000/cloud.html

The server stores runtime state in SQLite. By default it writes under the local cloud data directory configured by the server. In production, set a stable data directory or mount /data/noma so users, documents, sites, permissions, share links, and the block index survive container replacement.

Check the server:

curl http://localhost:3000/healthz
curl http://localhost:3000/api/status

Deploy with EZKeel from this repo:

npm run deploy:ezkeel:dry-run
npm run deploy:ezkeel

The EZKeel deployment uses Dockerfile, ezkeel.yaml, npm run build:cloud, node dist/cloud-server.js, and /data/noma as the storage root.

Protect the cloud app

Production deployments must provide a global token gate for the cloud app and cloud APIs plus a separate invitation code for user registration:

NOMA_CLOUD_ACCESS_TOKEN_FILE=/data/noma/access-token \
NOMA_CLOUD_INVITATION_CODE_FILE=/data/noma/invitation-code \
NOMA_CLOUD_SSO_TRUST_SECRET=<reverse-proxy-to-Noma-shared-secret> \
npm start

Noma Cloud refuses to start with NODE_ENV=production when either secret is missing. A deliberately public deployment can opt out explicitly with NOMA_CLOUD_ALLOW_OPEN_ACCESS=1 and/or NOMA_CLOUD_ALLOW_OPEN_REGISTRATION=1. API requests are rate-limited by client address; deployments behind a trusted reverse proxy should set NOMA_CLOUD_TRUST_PROXY=1. NOMA_CLOUD_RATE_LIMIT_MAX, NOMA_CLOUD_AUTH_RATE_LIMIT_MAX, and NOMA_CLOUD_RATE_LIMIT_WINDOW_MS tune the defaults.

Open the login page:

https://noma-cloud.apps.ezkeel.com/login.html

The login form validates the cloud access token, sets an HttpOnly cookie, and can import an existing Noma user token into the browser. New user registration is blocked unless the registration form includes the invitation code.

API clients must send the gate token separately from the normal Noma user token:

curl -H "X-Noma-Cloud-Access-Token: $NOMA_CLOUD_ACCESS_TOKEN" \
  -H "Authorization: Bearer $NOMA_TOKEN" \
  https://noma-cloud.apps.ezkeel.com/api/status

When the gate is enabled, cloud.html, the cloud editor assets, and /api/* return 401 without the access token. Browser visits to cloud.html redirect to login.html. Published document and site artifacts still require their own share tokens.

First workspace

After login, Noma Cloud uses a browser-stored Noma user token as the editing identity for API calls and UI permissions.

1. Pass the deployment gate in login.html when the server has a global access

token.

1. In the Cloud header, enter a name and invitation code, then choose

Register. On deliberately open development deployments the invitation field can stay empty.

1. To resume an existing identity, paste its user token in Token and choose

Log In. Sign Out clears that browser session without deleting data.

1. Use Copy User ID when another owner needs to invite you.
2. Use Copy Token only for your own API calls or plugin development.
3. Registration creates a starter workspace and paper page automatically.

Choose New Space when you need another research, book, or docs space.

1. Use New Page to add another paper section, chapter, or reference page,

then click pages in the left rail to switch documents.

The default first page is paper-oriented: abstract, research question, claim, evidence, methods, review table, findings, citation, bibliography, and review task. It is only a starter. Replace it with the structure your team needs.

Find, favorite, import, and recover content

The left rail provides workspace navigation beyond the page tree:

Search uses SQLite FTS5 plus deterministic local embeddings, typed metadata, wiki/trust edges, verification, and freshness. It always intersects results with the caller's page or space permissions. Trashed content is excluded from active lists, search, published spaces, and database queries. Moving a page to trash preserves its space membership so restoration returns it to the same workspace and folder.

Agents and integrations use the same lifecycle APIs:

GET    /api/search?q=<text>&site=<optional-site-id>&limit=25
GET    /api/knowledge/search?q=<text>&site=<optional-site-id>&limit=25
GET    /api/navigation
POST   /api/navigation/recent
PUT    /api/navigation/favorites
DELETE /api/navigation/favorites
GET    /api/templates
GET    /api/trash
POST   /api/trash/document/<id>
POST   /api/trash/document/<id>/restore
POST   /api/trash/site/<id>
POST   /api/trash/site/<id>/restore

When creating a page through /api/documents or /api/sites/<site-id>/documents, send templateId instead of source, or send format: "markdown" with Markdown source for server-side intake.

Ask Noma, trust, and knowledge health

The Ask Noma inspector is retrieval-first rather than a generic chat box. An answer is returned only when the caller can access sufficiently relevant evidence. Every citation includes the document ID, stable block ID, exact source span, current document hash, content type, trust/freshness metadata, provenance, relevance score, and the access decision made for that query.

When evidence is weak, Noma returns insufficient_evidence with no invented citations. When canonical sources disagree, the answer keeps the conflicting claims visible instead of averaging them silently.

Trust metadata can be attached to any stable block:

The knowledge health queue detects stale/review-due blocks, pages without resolved links, broken wiki targets, semantic duplicate candidates, contradictory canonical claims, missing owners, and unanswered questions. LLM Wiki mode adds suggested links, missing concept pages, canonical concepts, typed relationships, and proof-first merge drafts.

POST /api/ask
GET  /api/knowledge/search
GET  /api/knowledge/llm
GET  /api/knowledge/health
GET  /api/knowledge/wiki
POST /api/knowledge/reindex
GET|PUT /api/knowledge/trust/<document-id>/<block-id>
POST /api/knowledge/evaluations

Evaluation fixtures declare required and forbidden sources plus abstention, latency, and cost expectations. Each run records source recall, forbidden hits, citation coverage, permission leakage, stale-source use, abstention correctness, latency, and estimated cost.

Scoped agents and the shared change inbox

An agent identity has its own model policy, zero-retention flag, capability set, page/space grants, budget, spend, status, and run history. Supplying an agent ID to Ask or the gateway intersects the human-visible workspace with the agent's explicit grants. It never inherits the triggering human's other pages.

The shared agent change inbox enriches each existing proofed patch proposal with its plan, source versions, requested capabilities, operations, diff, pre/post validation, affected stable IDs, reviewer, and apply state. Agents can proof and propose; a different editor must approve, and apply rechecks the current document hash.

GET|POST /api/agents
GET|POST /api/agents/<agent-id>/access
GET|POST /api/agents/<agent-id>/runs
POST     /api/agents/<agent-id>/runs/<run-id>/complete
GET      /api/agent-inbox

External tools use the same permission and proof path through REST, webhook, or JSON-RPC MCP:

GET  /api/gateway
POST /api/gateway/list-ids
POST /api/gateway/mcp
POST /api/gateway/webhooks/<recipe-id>

MCP tools cover scoped search, cited answers, ID discovery, proof, proposal, human review, and hash-checked apply. tools/list and tools/call use JSON-RPC 2.0; tool results include both MCP text content and structured content.

Connected and self-maintaining knowledge

Connector record contracts support GitHub, Slack, Google Drive, Jira, Linear, and filesystem sources. Every recorded source retains upstream permissions, modified time, source URL, content hash, predecessor lineage, synchronization time, and deletion tombstone rather than erasing its history.

Six built-in proposal templates cover stale-document review, meeting-to-decision, issue-to-runbook, research refresh, onboarding answers, and release maintenance. Manual, schedule, event, and webhook trigger intent is explicit; an external scheduler or worker invokes those routes. A recipe run produces a plan and proof_proposal_only mutation policy; it never writes around the agent review contract.

Semantic collections query typed blocks across permitted pages: open decisions, claims missing evidence, risks by owner, stale citations, and agent changes awaiting review. Analytics count no-result queries, generated and rejected answers, citation opens, and completed tasks only inside the caller's accessible document scope.

GET|POST /api/connectors
GET|POST /api/connectors/<connector-id>/sources
GET|POST /api/recipes
GET|POST /api/recipes/<recipe-id>/runs
GET      /api/collections
GET|POST /api/analytics

Portable backup, offline recovery, and realtime humans

POST /api/backup/export produces a deterministic .noma bundle sorted by document ID, with per-file hashes, one bundle digest, and optional repository, branch, and pull-request-review metadata. Import verifies every source hash, reports corrupt bundles and concurrent edits, and applies creates/updates only when the conflict plan is clean. Canonical content remains reconstructable plain .noma source.

Noma Cloud is an installable PWA. The service worker caches the application shell, while each edit stores a full local draft containing base hash, base source, draft source, title, user, document ID, and timestamp. A draft whose base still matches is restored automatically. If the server changed, the UI offers explicit recover, three-way merge, or discard choices and renders conflict markers rather than overwriting either author.

Realtime human operations use the same stable IDs, proof engine, expected hash, immutable document revisions, and ordered operation sequence as normal writes. The feed is pollable with after=<sequence>. Realtime operations reject agent actors; asynchronous proofed proposals remain the agent default.

POST /api/backup/export
POST /api/backup/import
GET|POST /api/offline/drafts
POST /api/offline/drafts/<draft-id>/merge
GET|POST /api/realtime/documents/<document-id>/operations

Enterprise policy

Workspace-owner enterprise policy configures trusted-proxy OIDC/SAML login, SCIM identity records, platform-metadata retention days and legal hold, declared data residency, connector allowlists, model allowlists, zero-retention model requirements, and audit export. Connector and agent creation enforce the active allowlists immediately. Agent completion cannot exceed its remaining spend budget. Retention cleanup excludes records protected by an active legal hold.

GET|PUT  /api/enterprise
POST      /api/auth/sso
GET|POST /api/enterprise/scim
GET|POST /api/enterprise/legal-holds
GET       /api/enterprise/audit
POST      /api/enterprise/retention

Collaborate, notify, and approve

The inspector keeps review context beside the source instead of scattering it across email and a separate ticket system:

Mention another collaborator with the stable syntax @{user-id}. Mentions are delivered only when that user can access the document. A group grant never copies hidden direct permissions to every member: search, navigation, API reads, and edit checks resolve current membership at request time.

Core collaboration routes are available in both standalone document form and under /api/sites/<site-id>/documents/<document-id>:

GET|POST /api/documents/<id>/comments
POST     /api/documents/<id>/comments/<comment-id>/resolve
GET|POST /api/documents/<id>/approvals
PATCH    /api/documents/<id>/approvals/<approval-id>
GET      /api/notifications
POST     /api/notifications/read-all
GET      /api/activity?document=<id>&site=<id>
GET|POST /api/groups
POST     /api/groups/<id>/members
GET|POST /api/documents/<id>/group-collaborators

Manage work beside knowledge

The Work inspector gives each space an integrated Jira-style project. This keeps delivery context attached to the specs, decisions, research, and runbooks that define the work.

Projects support:

• unique keys such as NOM, producing stable issue keys like NOM-42
• task, story, bug, and epic issue types
• backlog, to-do, in-progress, in-review, and done workflow states with checked transitions
• priorities, assignees, labels, estimates, due dates, and parent issues
• query filters over text, status, type, priority, assignee, label, and sprint
• board columns, a no-sprint backlog, planned/active/closed sprints, and one active sprint per project
• unfinished-work carry-over when a sprint closes
• issue comments, related/blocks/duplicates links, and immutable issue change history

Project access comes from its space, including group grants. Viewers can browse and comment; editors can create and transition issues, manage sprints, and add links. The bounded API is suitable for agents and integrations:

GET|POST /api/projects
GET|PATCH /api/projects/<project-id-or-key>
GET|POST /api/projects/<id>/issues
GET|PATCH /api/projects/<id>/issues/<issue-id-or-key>
GET|POST /api/projects/<id>/issues/<issue>/comments
GET|POST /api/projects/<id>/issues/<issue>/links
GET      /api/projects/<id>/issues/<issue>/history
GET      /api/projects/<id>/board
GET      /api/projects/<id>/backlog
GET|POST /api/projects/<id>/sprints
GET|PATCH /api/projects/<id>/sprints/<sprint-id>

Edit a page

The center of the app has two panes:

Use the view switch in the page header when the workspace feels too dense:

In Preview mode, owners and editors can click rendered headings, paragraphs, list items, and quotes to edit them directly. Those edits sync back to the matching source lines and mark the page unsaved. Semantic blocks, tables, citations, figures, and agent patches remain source-first so structured metadata is not rewritten accidentally. Use Panels when you need the workspace rail, share controls, diagnostics, or outline again.

Mouse editing is available in Preview mode:

Link pages like Obsidian

Noma Cloud supports page-oriented wikilinks for LLM wiki workflows:

In the preview, click a resolved page link to open that page. Click a missing page link as an editor to create a new wiki page with a summary, notes, related links, and an agent maintenance task. The Wiki inspector shows outgoing links, backlinks, and missing pages for the current page.

The server exposes the same graph through the API:

curl -H "X-Noma-Cloud-Access-Token: $NOMA_CLOUD_ACCESS_TOKEN" \
  -H "Authorization: Bearer $NOMA_TOKEN" \
  https://noma-cloud.apps.ezkeel.com/api/sites/<site-id>/wiki

The response includes pages, links, backlinks, and missing so a Codex plugin can query the wiki graph without scraping rendered HTML.

Use stable IDs on headings and semantic blocks:

# Research Paper Draft {id="research-paper-draft"}

::claim{id="claim-main" confidence=0.72}
The core claim goes here.
::

::evidence{id="evidence-primary" for="claim-main" source="source-primary"}
The strongest evidence goes here.
::

Click Save when the diagnostics are acceptable. Every save includes the hash of the version you loaded. If another human or agent saved first, Noma keeps your draft intact and reports a conflict instead of overwriting their work. Use Reload to discard the draft and open the latest saved page.

The History panel lists every saved content version. Owners and editors can restore an older version; restoration creates a new version, so the versions between the old state and the restored state remain available for comparison and audit. Permission and share-link changes do not create noisy content versions.

The cloud server stores the source, title, hash, immutable revision history, diagnostics, and block index in SQLite.

Scientific-paper workflow

For papers and technical research, keep each reviewable idea in an addressable block:

This shape matters because collaborators and agents can target exactly claim-main, evidence-primary, or review-checklist instead of editing the whole document.

For journal or committee handoff, use the CLI from the saved source:

noma render paper.noma --to html --strict --out paper.html
noma render paper.noma --to pdf --out paper.pdf
noma render paper.noma --to docx --out paper.docx
noma docx-review-sync paper.noma reviewed-paper.docx --out paper.reviewed.noma --report review-sync.json

Cloud is the shared workspace. The CLI remains the strongest release path for PDF, DOCX, strict publishing, CI, and source-controlled review.

Share and permissions

Noma Cloud has three roles:

Owners can invite another browser user by pasting that user's ID into Invite user ID and choosing viewer or editor. Space access is inherited by its pages, including pages created later. Owners can also invite a managed group; changing group membership immediately changes effective access without rewriting each page's permission list.

Share links are token-based:

Viewer links make the source readonly in the app. Editor links can save the page. API query endpoints do not accept share tokens for raw database access; they require a real Noma Cloud user token.

Proofed agent review linked to work

The Agent Review panel accepts one patch op or an array of patch ops in JSON. Preview in Draft runs a local parse/validation preview without saving. Propose for Review sends the operations to the server, where Noma creates a safety proof against the current saved document hash. If a Work issue is selected, the proposal and every later review/apply event are linked into that issue's immutable history.

The proof records pre/post hashes, patch result, diagnostics, stable IDs, source-preservation metrics, a compact diff, and a sandboxed post-patch artifact preview. A different editor must approve the proposal. Apply re-runs the proof against the current source and rejects the proposal if a human or agent changed the document after it was proposed. Self-approval, failed proofs, unapproved apply attempts, and stale versions are blocked.

Example:

[
  {
    "op": "replace_body",
    "id": "claim-main",
    "content": "The revised central claim goes here."
  }
]

Common ops:

Use Copy LLM to copy deterministic LLM context for the current page. That context strips unsafe escape hatch bodies and keeps block IDs visible so an agent can propose a focused patch transaction.

The same review gate is available to API clients:

GET|POST /api/documents/<id>/patch-proposals
GET      /api/documents/<id>/patch-proposals/<proposal-id>
POST     /api/documents/<id>/patch-proposals/<proposal-id>/review
POST     /api/documents/<id>/patch-proposals/<proposal-id>/apply

Create proposals with { "ops": [...], "issueId": "optional-issue-id" }. Review with { "decision": "approved" } or "rejected". The document and linked issue both receive auditable proposed, approved/rejected, and applied events.

Published sites and artifacts

Use Artifact when you want one page as a reader artifact. Use Published when the workspace should become a multi-page reader site with page navigation.

These routes are generated from the same saved source:

Query the DB API

The DB API is intentionally not raw SQL. It is a bounded JSON query surface for future plugins and agent tools.

Read the available resources:

curl -H "authorization: Bearer $NOMA_TOKEN" \
  http://localhost:3000/api/db/schema

Query blocks:

curl -X POST \
  -H "authorization: Bearer $NOMA_TOKEN" \
  -H "content-type: application/json" \
  -d '{"resource":"blocks","q":"claim","limit":10}' \
  http://localhost:3000/api/db/query

Query documents in a workspace:

curl -X POST \
  -H "authorization: Bearer $NOMA_TOKEN" \
  -H "content-type: application/json" \
  -d '{"resource":"documents","siteId":"site-id","limit":20}' \
  http://localhost:3000/api/db/query

Resources:

Every result is filtered by the caller's Noma Cloud permissions. Tokens copied from share links are for document/site access, not database inspection.

Mobile and tablet use

On small screens the app stacks the top bar, workspace rail, editor, preview, and inspector vertically. This is useful for review and light editing. Long authoring sessions are still better on desktop because the source and preview can remain side by side.

Safety model

Noma Cloud follows the same safety posture as the workbench:

• the preview runs in a sandboxed iframe
• raw ::html, ::svg, and ::script escape hatches are blocked in preview
• external figure, math, diagram, and Plotly loads are disabled in preview
• permissions are checked on document, site, export, share, collaborator, and DB endpoints
• group grants are resolved dynamically and participate in the same permission checks
• approvals and agent patch proposals are bound to immutable document hashes
• agent patches are re-proofed after independent review and immediately before apply
• share links are role-scoped and token-based
• DB queries are resource-bounded and permission-aware, not arbitrary SQL
• request bodies have size limits
• server-side render paths escape user source before artifact output

For repository changes, run:

npx tsc --noEmit
npm test
npm run build:site

For browser acceptance, verify owner, editor, viewer, page edit, site edit, group inheritance, comments, mentions, notifications, approvals, project/issue workflows, sprint carry-over, issue-linked patch review, share links, published site, artifact export, DB schema/query, diagnostics, mobile layout, and XSS payload handling.

Troubleshooting

Noma Cloud is the collaboration layer. The .noma source, renderer outputs, block IDs, validator, proof/patch ops, and CLI remain the durable product contract underneath it.

For the market evidence and the next agent-human knowledge roadmap -- including block-native RAG, Ask Noma, LLM Wiki maintenance, scoped agent identities, knowledge health, connectors, and offline/realtime sequencing -- see Agent-Human Knowledge Platform Research and PLAN.md §26.