---
{
  "id": "platform.doc.permissions-versioning-and-collaboration",
  "topic": "doc",
  "title": "Doc permissions, version counters, and collaboration",
  "locale": "en",
  "version": "2026-08-25",
  "summary": "Doc access is the intersection of user authority and Agent grants; metadata versions are concurrency counters, and collaboration errors must preserve persisted-write semantics.",
  "content": "Doc access intersects triggering-user authority with the Agent grant. Personal Docs require a direct grant; shared-space Docs accept a direct or Space grant. Read-only writes return `permission_denied`; no effective read authority returns `resource_not_found`, indistinguishable from a missing Doc. `list_docs` returns only the user-visible ∩ Agent-readable set, so absence is not proof of nonexistence.\n\nMetadata `version` is an optimistic concurrency counter distinct from durable history. Private history Actions are `list_versions`, `get_version`, `create_named_version`, and `restore_version`. Named checkpoints need no confirmation and use Strict drift. Restore requires UserConfirm, `docId`, `versionId`, and current `expectedVersion`; it saves a pre-restore checkpoint and rolls forward. On `resource_conflict`, call `get_doc` again. Never blindly resend.\n\nSuccessful writes are persisted before synchronization to the Yjs live collaboration room. “Saved but collaboration sync failed” means persistence succeeded while the live room may temporarily lag; safely reread to confirm rather than reporting data loss.\n\n`archive_doc` requires write access and removes the Doc from active lists. `unarchive_doc` reverses that lifecycle state with the same owner/resource/space-grant checks; both mutations are audit-attributed to the executing Agent. `includeArchived: true` can list an archived Doc and `get_doc` can still read it.\n\nPermanent `delete_doc` is available only after the Doc is archived. It requires UserConfirm and Strict drift, and cannot be used as a shortcut around archive-first lifecycle safety.\n\n`export_doc` accepts PDF, DOCX, HTML, or Markdown and stores it in personal File Center. It resolves authorized ready images and never fetches external URLs. Dry-run creates no file; runtime remains authoritative.\n",
  "aliases": [
    "Doc permission",
    "document grant",
    "version conflict",
    "collaboration sync",
    "archive document",
    "shared space document",
    "文件權限"
  ],
  "tags": [
    "doc",
    "permissions",
    "concurrency",
    "collaboration"
  ],
  "relatedActions": [
    "arinova.doc.get_doc",
    "arinova.doc.list_docs",
    "arinova.doc.archive_doc",
    "arinova.doc.unarchive_doc",
    "arinova.doc.export_doc",
    "arinova.doc.update_doc",
    "arinova.doc.append_content",
    "arinova.doc.set_page_settings",
    "arinova.doc.format_text",
    "arinova.doc.format_block",
    "arinova.doc.list_versions",
    "arinova.doc.get_version",
    "arinova.doc.create_named_version",
    "arinova.doc.restore_version",
    "arinova.doc.delete_doc"
  ],
  "relatedActionPrefixes": [],
  "url": "https://docs.arinova.ai/en/kb/doc/permissions-versioning-and-collaboration/"
}
---

Doc access intersects triggering-user authority with the Agent grant. Personal Docs require a direct grant; shared-space Docs accept a direct or Space grant. Read-only writes return `permission_denied`; no effective read authority returns `resource_not_found`, indistinguishable from a missing Doc. `list_docs` returns only the user-visible ∩ Agent-readable set, so absence is not proof of nonexistence.

Metadata `version` is an optimistic concurrency counter distinct from durable history. Private history Actions are `list_versions`, `get_version`, `create_named_version`, and `restore_version`. Named checkpoints need no confirmation and use Strict drift. Restore requires UserConfirm, `docId`, `versionId`, and current `expectedVersion`; it saves a pre-restore checkpoint and rolls forward. On `resource_conflict`, call `get_doc` again. Never blindly resend.

Successful writes are persisted before synchronization to the Yjs live collaboration room. “Saved but collaboration sync failed” means persistence succeeded while the live room may temporarily lag; safely reread to confirm rather than reporting data loss.

`archive_doc` requires write access and removes the Doc from active lists. `unarchive_doc` reverses that lifecycle state with the same owner/resource/space-grant checks; both mutations are audit-attributed to the executing Agent. `includeArchived: true` can list an archived Doc and `get_doc` can still read it.

Permanent `delete_doc` is available only after the Doc is archived. It requires UserConfirm and Strict drift, and cannot be used as a shortcut around archive-first lifecycle safety.

`export_doc` accepts PDF, DOCX, HTML, or Markdown and stores it in personal File Center. It resolves authorized ready images and never fetches external URLs. Dry-run creates no file; runtime remains authoritative.