document-workspace

name	Document Workspace
catalog_line	Project document hierarchy: doc tree operations, unlinked docs, task docs, document CRUD rules.
description	Project document hierarchy playbook for doc tree operations, unlinked docs, task docs, and document CRUD rules.
skill_type	procedure
altitude	task
activation	progressive
preserve_markdown	true
legacy_paths	["onto.document.skill"]
path	apps/web/src/lib/services/agentic-chat/tools/skills/definitions/document_workspace/SKILL.md

Document Workspace

Identity

Project document hierarchy playbook for doc tree operations, unlinked docs, task docs, and document CRUD rules. This is a procedure skill at task altitude: an ordered runbook for placing, reorganizing, linking, and writing project documents safely.

Activation

• Create or place a project document in the doc tree
• Reorganize project documents
• Link unlinked docs back into the tree
• Decide whether a document belongs in the project tree or a task workspace
• Reason about document hierarchy safely

Procedure

1. Decide whether the request is about a project document or a task document.
2. For project documents, remember the hierarchy lives in doc_structure, not in document-to-document edges.
3. For project document creation, include at least project_id and title. Include description whenever available; some direct tool surfaces require it.
4. Placement can happen at create time. When creating a project document that should be nested, pass parent_id and optional position on create_onto_document / onto.document.create. Use move_document_in_tree / onto.document.tree.move for existing documents, unlinked documents, or later reorganization. Only claim "nested under X" or "placed in" after the create response returns without a tree placement error or a move call succeeds.
5. For task workspace documents, use onto.task.docs.* instead of the project doc tree.
6. For reorganization or linking unlinked docs, call onto.document.tree.get once, analyze the result, then issue targeted onto.document.tree.move calls.
7. When moving a document, pass exact document_id and new_position; use new_parent_id only when nesting under a parent.
8. Append and merge writes require non-empty content. For onto.document.update calls with update_strategy: "append" or update_strategy: "merge_llm", always include the actual text to persist. merge_instructions alone is not enough — merge/append behavior requires content to merge. The executor will reject no-content append/merge calls.
9. Only create semantic edges to documents from other entities when that relationship is useful; do not use edges to represent folder structure.

Contract

After a document write, report:

• What changed: document title, type, and the content action (created, replaced, appended, or merged).