@graph8/sdk 0.370.0 → 0.374.0

package/blocks/documents/README.md

@@ -0,0 +1,86 @@
+# documents
+
+The paperwork around selling, in one block: the organization's **document Library** (folders, files, text), **security
+questionnaires** a buyer sends (graph8 answers them from your Library, a person reviews every answer, the filled workbook
+comes back out) and the **correspondence** recorded against an account. 35 operations of the `documents` namespace; every one
+is reachable from `DocumentsScreen`.
+
+## Screens
+
+`DocumentsScreen` (`components/documents-screen.tsx`) is the finished page.
+
+```tsx
+import { DocumentsScreen } from "@/g8/documents/components/documents-screen";
+export default function Page() { return <DocumentsScreen />; }
+```
+
+Tabs (`?tab=`): **Library**, **Security questionnaires**, **Correspondence**. The two account tabs share one account (`?account=<company id>`), so a link opens straight to a company's paperwork.
+
+- **Library**: folders on one side, documents on the other (search; filter by type and source; Show removed). Open a document (`?id=`) to read its text and facts, download the **original** file, edit it (title, folder, text), read a PDF or Word file's text again, refresh a scraped page, restore a removed one, or delete it (confirmed, permanent). Make, rename and delete folders (an empty folder only). Write a text document. Upload one or many files (checked against the Library's file types and the size limit first; a batch reports each file and keeps the failures selected for a retry). Read the text of every PDF and Word file again, or of one folder (confirmed, counted from the files it will touch).
+- **Security questionnaires**: an account's questionnaires (status filter, Load more). Upload an XLSX or PDF (**confirmed; answering uses credits**), follow its progress, review every question (edit the answer, approve, escalate with notes, mark not applicable, mark wrong, save to the answer library), download the filled workbook, rename or delete it (confirmed).
+- **Correspondence**: what has been said to an account (filter by channel and person, Load more). Record a message, import a JSON batch or one text file, delete (confirmed).
+
+Optional props: `renderRowActions`, `renderDetailActions`, `extraDetailTabs` (Library documents), `toolbarActions`, `maxBytes`.
+
+Parts you can mount alone: `LibraryPanel`, `LibraryDocumentDetail`, `LibraryDocumentForm`, `LibraryFolderForm`, `LibraryUpload`, `QuestionnairesPanel`, `QuestionnaireDetail`, `QuestionRow`, `CorrespondencePanel`, `CorrespondenceForm`, `CorrespondenceImport`, `AccountBar`.
+
+### On a company, contact or deal page
+
+`RecordDocumentsTab` shows the newest messages and questionnaires for the account behind a record, read only, with a link into `DocumentsScreen` that has the account chosen. Mount it through the `extraDetailTabs` slot:
+
+```tsx
+<CompaniesScreen extraDetailTabs={[{ id: "documents", label: "Documents", render: (c) => <RecordDocumentsTab companyId={c.id} onOpenDocuments={(href) => router.push(href)} /> }]} />
+<ContactsScreen  extraDetailTabs={[{ id: "documents", label: "Documents", render: (c) => <RecordDocumentsTab contactId={c.id} /> }]} />
+<DealsScreen     extraDetailTabs={[{ id: "documents", label: "Documents", render: (d) => <RecordDocumentsTab contactId={d.primary_contact?.id} scope="account" /> }]} />
+```
+
+A contact shows their **company's** paperwork with the messages involving them. A deal has no company on the record the deals block reads, so it goes through its primary contact to find the company (`scope="account"` shows all the company's messages, not only that contact's); a deal with no contact shows an empty state.
+
+## Install
+
+```
+npx @graph8/sdk add documents
+```
+
+Installs `foundation` and `pickers` first if missing. Everything lands under `g8/documents/`.
+
+## Prerequisites (the human must do these)
+
+| Where | What | How to verify |
+|---|---|---|
+| graph8 key | `knowledge:read`, `knowledge:write`, `knowledge:delete` (Library); `companies:read`, `companies:write`, `companies:delete` (questionnaires, correspondence); `knowledge:run` to upload a questionnaire (billable, separate from `knowledge:write`); `contacts:read` for the person picker. | `g8.api.me.describeCurrentKey()` |
+| Your app | `allowedPrefixes` must include `library`, `accounts`, `companies`, `contacts`. The endpoints live under `/library` and `/accounts`, not `/documents`. | The route file lists them. |
+| Your app | The proxy caps the WHOLE request body at **5 MiB** by default; the Library takes files up to 50 MB. The screen keeps every file (and every request, for a multi-file upload, which is split into several requests) under that cap. To allow more, raise `maxBodyBytes` in `app/api/g8/[...path]/route.ts` and pass the same number as `maxBytes`. | An upload near the limit succeeds. |
+| The business | Your **Library** holds the security policies and past answers before the first questionnaire is uploaded; answering draws on them. A person decides to spend credits on each upload. | The Library has the documents the buyer's questions draw on. |
+
+## The flow, in order (IDs passed between steps)
+
+1. `getLibraryTree` first (the API creates the preset folders `Security` and `Case Studies` when the tree is read), then `listLibraryFolders` (`full_path` is what documents are filed under) and `listLibraryDocuments` (`items`, each with `id`, `folder_path`, `file_type`, `has_file_data`).
+2. `createLibraryFolder` ({ name, parent_path }) then `uploadLibraryDocument` / `uploadLibraryDocuments` (multipart `folder_path` + file/files) or `createLibraryDocument` ({ folder_path, file_name, display_name, content }). The folder must exist.
+3. `getLibraryDocument` (`id`) for the text; `updateLibraryDocument` sends only changed fields; `downloadLibraryDocument` returns the original bytes; `deleteLibraryDocument` is permanent; `restoreLibraryDocument` undoes only a soft delete (find those with `include_deleted=true`).
+4. Questionnaires: `uploadSecurityQuestionnaire` (account id = a company id; multipart `file`, xlsx or pdf) returns the questionnaire `id`; poll `getSecurityQuestionnaireStatus`; read `getSecurityQuestionnaire` for the questions; act with `updateQuestionnaireAnswer`, `approveQuestionnaireAnswer`, `escalateQuestionnaireQuestion`, `skipQuestionnaireQuestion`, `flagQuestionnaireAnswer`, `saveQuestionnaireAnswerToLibrary`; `downloadSecurityQuestionnaire` once `completed` or `needs_review`.
+5. Correspondence: `createAccountCorrespondence`, `importAccountCorrespondence` (send `external_id` to make a re-run skip duplicates), `uploadAccountCorrespondence` (a text file; dated now), `listAccountCorrespondence` (`channel`, `stakeholder_id`, `limit`, `offset`), `deleteAccountCorrespondence`.
+
+## Defaults the block chose (so the agent need not ask)
+
+| Decision | Default | Ask the human? |
+|---|---|---|
+| Which library | The organization's (global) Library. The campaign and account libraries are not offered (see gaps) | no |
+| Where an upload lands | The open folder, else the Library root; changeable | no |
+| File size limit | 5 MiB (the proxy default) | no |
+| Uploading a questionnaire | Never without a person confirming | yes |
+| Approving an answer | A person reads it and approves; nothing is automatic | yes |
+| Channel and direction of a message | None: the person chooses | yes |
+| Deleting | Always confirmed; cannot be brought back | no |
+
+## Known API gaps (from reading the backend; the block works around them and says so on screen)
+
+- **No price for questionnaire answering.** It is billable (`knowledge:run`) but there is no read for the cost, so the confirmation says it uses credits and shows no number.
+- **`refreshLibraryDocument` is not implemented upstream**: for a scraped page it answers `status: "info"` with a message that refresh is not available yet. The screen shows that message as it is and never says the page was refreshed.
+- **`deleteLibraryDocument` is a hard delete** (row and bytes), and only the owner or an admin may do it (403 otherwise). `restoreLibraryDocument` only applies to documents soft-deleted elsewhere (`include_deleted=true`).
+- **Account and campaign libraries read and write with different ids**: `GET /library/documents` and `GET /library/folders` filter on the raw `account_id`/`campaign_id`, while `GET /library/tree` resolves a company id to its overlay id. A document filed under an account can be listed by one and missing from the other, so the block offers the global Library only.
+- **`reextractAllLibraryDocuments` matches the folder by path prefix** (`folder_path LIKE 'x%'`), so `Library/Cases` also matches `Library/Cases 2`. The confirmation counts with the same prefix rule.
+- **`GET /library/tree` leaves out folders deeper than one level and includes soft-deleted documents**, so the block counts from the flat lists.
+- **Batch upload** returns `success` / `failed` (and no `items`), at most 20 files, and the first extension or size problem fails only that file.
+- **Uploaded correspondence is dated now** (no date field on the upload) and read as UTF-8 or Latin-1 text.
+- **Open response bodies**: every documents response is a free-form object in the contract, so the block reads fields defensively and shows a dash for anything missing.

package/blocks/documents/block.json

@@ -0,0 +1,378 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "documents",
+  "title": "Documents",
+  "summary": "The document Library (folders, files, text), buyers' security questionnaires answered and reviewed per account, and account correspondence: browse, upload, edit, review, download.",
+  "features": [
+    "Library: folders, search and filters, text and original-file download, edit, upload one or many files, write a text document, restore a removed one, delete with confirmation",
+    "re-read the text of PDF and Word files, one or a whole folder, counted and confirmed",
+    "security questionnaires per account: upload (confirmed, uses credits), live progress, review every answer, download the filled workbook",
+    "review actions per question: edit the answer, approve, escalate with notes, mark not applicable, mark wrong, save to the answer library",
+    "account correspondence: record a message, import a JSON batch or a text file, filter by channel and person, delete with confirmation",
+    "RecordDocumentsTab: the latest messages and questionnaires on a company, contact or deal page"
+  ],
+  "dependsOn": [
+    "pickers"
+  ],
+  "operations": [
+    "approve_questionnaire_answer_accounts__account_id__security_questionnaires__questionnaire_id__questions__question_id__approve_post",
+    "create_account_correspondence_accounts__account_id__correspondence_post",
+    "create_library_document_library_documents_post",
+    "create_library_folder_library_folders_post",
+    "delete_account_correspondence_accounts__account_id__correspondence__correspondence_id__delete",
+    "delete_library_document_library_documents__doc_id__delete",
+    "delete_library_document_library_documents__document_id__delete",
+    "delete_library_folder_library_folders__folder_id__delete",
+    "delete_security_questionnaire_accounts__account_id__security_questionnaires__questionnaire_id__delete",
+    "download_library_document_library_documents__document_id__download_get",
+    "download_security_questionnaire_accounts__account_id__security_questionnaires__questionnaire_id__download_get",
+    "escalate_questionnaire_question_accounts__account_id__security_questionnaires__questionnaire_id__questions__question_id__escalate_post",
+    "flag_questionnaire_answer_accounts__account_id__security_questionnaires__questionnaire_id__questions__question_id__mark_wrong_post",
+    "get_company_companies__company_id__get",
+    "get_contact_contacts__contact_id__get",
+    "get_library_document_library_documents__doc_id__get",
+    "get_library_document_library_documents__document_id__get",
+    "get_library_tree_library_tree_get",
+    "get_security_questionnaire_accounts__account_id__security_questionnaires__questionnaire_id__get",
+    "get_security_questionnaire_status_accounts__account_id__security_questionnaires__questionnaire_id__status_get",
+    "import_account_correspondence_accounts__account_id__correspondence_import_post",
+    "list_account_correspondence_accounts__account_id__correspondence_get",
+    "list_companies_companies_get",
+    "list_contacts_contacts_get",
+    "list_library_documents_library_documents_get",
+    "list_library_folders_library_folders_get",
+    "list_security_questionnaires_accounts__account_id__security_questionnaires_get",
+    "reextract_all_library_documents_library_documents_reextract_all_post",
+    "reextract_library_document_library_documents__doc_id__reextract_post",
+    "reextract_library_document_library_documents__document_id__reextract_post",
+    "refresh_library_document_library_documents__doc_id__refresh_post",
+    "refresh_library_document_library_documents__document_id__refresh_post",
+    "rename_library_folder_library_folders__folder_id__put",
+    "restore_library_document_library_documents__doc_id__restore_post",
+    "restore_library_document_library_documents__document_id__restore_post",
+    "save_questionnaire_answer_to_library_accounts__account_id__security_questionnaires__questionnaire_id__questions__question_id__save_to_library_post",
+    "skip_questionnaire_question_accounts__account_id__security_questionnaires__questionnaire_id__questions__question_id__mark_skip_post",
+    "update_library_document_library_documents__doc_id__put",
+    "update_library_document_library_documents__document_id__put",
+    "update_questionnaire_answer_accounts__account_id__security_questionnaires__questionnaire_id__questions__question_id__patch",
+    "update_security_questionnaire_accounts__account_id__security_questionnaires__questionnaire_id__patch",
+    "upload_account_correspondence_accounts__account_id__correspondence_upload_post",
+    "upload_library_document_library_documents_upload_post",
+    "upload_library_documents_library_documents_upload_batch_post",
+    "upload_security_questionnaire_accounts__account_id__security_questionnaires_post"
+  ],
+  "components": [
+    {
+      "name": "DocumentsScreen",
+      "file": "components/documents-screen.tsx",
+      "purpose": "Finished documents workspace: the organization's document Library, an account's security questionnaires with the review loop, and an account's correspondence; composes the parts below.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "LibraryPanel",
+      "file": "components/library-panel.tsx",
+      "purpose": "The Library page: folder rail, searchable document list with filters and stats, the selected document, new folder, new document, upload; deletes an empty folder and re-reads the text of PDF and Word files, both behind a confirmation counted from what is sent.",
+      "operations": [
+        "delete_library_folder_library_folders__folder_id__delete",
+        "get_library_tree_library_tree_get",
+        "list_library_documents_library_documents_get",
+        "list_library_folders_library_folders_get",
+        "reextract_all_library_documents_library_documents_reextract_all_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "LibraryDocumentDetail",
+      "file": "components/library-document-detail.tsx",
+      "purpose": "One Library document: its text, its facts, download of the original, edit, read the text again, refresh a scraped page, restore, and permanent delete behind a confirmation.",
+      "operations": [
+        "delete_library_document_library_documents__doc_id__delete",
+        "delete_library_document_library_documents__document_id__delete",
+        "download_library_document_library_documents__document_id__download_get",
+        "get_library_document_library_documents__doc_id__get",
+        "get_library_document_library_documents__document_id__get",
+        "reextract_library_document_library_documents__doc_id__reextract_post",
+        "reextract_library_document_library_documents__document_id__reextract_post",
+        "refresh_library_document_library_documents__doc_id__refresh_post",
+        "refresh_library_document_library_documents__document_id__refresh_post",
+        "restore_library_document_library_documents__doc_id__restore_post",
+        "restore_library_document_library_documents__document_id__restore_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "LibraryDocumentForm",
+      "file": "components/library-document-form.tsx",
+      "purpose": "Write a text document into the Library, or edit one; edit reads the full record first and sends only changed fields.",
+      "operations": [
+        "create_library_document_library_documents_post",
+        "get_library_document_library_documents__doc_id__get",
+        "get_library_document_library_documents__document_id__get",
+        "update_library_document_library_documents__doc_id__put",
+        "update_library_document_library_documents__document_id__put"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "LibraryFolderForm",
+      "file": "components/library-folder-form.tsx",
+      "purpose": "Create a Library folder or rename one, with the API's name and depth rules checked first.",
+      "operations": [
+        "create_library_folder_library_folders_post",
+        "rename_library_folder_library_folders__folder_id__put"
+      ],
+      "tiers": [
+        "write"
+      ]
+    },
+    {
+      "name": "LibraryUpload",
+      "file": "components/library-upload.tsx",
+      "purpose": "Add one or many files to a Library folder, checked against the Library's types and the proxy's size limit; a batch reports each file and keeps the failures selected for a retry.",
+      "operations": [
+        "upload_library_document_library_documents_upload_post",
+        "upload_library_documents_library_documents_upload_batch_post"
+      ],
+      "tiers": [
+        "write"
+      ]
+    },
+    {
+      "name": "QuestionnairesPanel",
+      "file": "components/questionnaires-panel.tsx",
+      "purpose": "An account's security questionnaires: list with status filter and Load more, upload a new one (billable, confirmed), and the selected questionnaire's review.",
+      "operations": [
+        "list_security_questionnaires_accounts__account_id__security_questionnaires_get",
+        "upload_security_questionnaire_accounts__account_id__security_questionnaires_post"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "QuestionnaireDetail",
+      "file": "components/questionnaire-detail.tsx",
+      "purpose": "One security questionnaire: live progress while it is answered, every question with filters, download of the filled workbook, rename, and delete behind a confirmation.",
+      "operations": [
+        "delete_security_questionnaire_accounts__account_id__security_questionnaires__questionnaire_id__delete",
+        "download_security_questionnaire_accounts__account_id__security_questionnaires__questionnaire_id__download_get",
+        "get_security_questionnaire_accounts__account_id__security_questionnaires__questionnaire_id__get",
+        "get_security_questionnaire_status_accounts__account_id__security_questionnaires__questionnaire_id__status_get",
+        "update_security_questionnaire_accounts__account_id__security_questionnaires__questionnaire_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "QuestionRow",
+      "file": "components/question-row.tsx",
+      "purpose": "One questionnaire question with the AI's answer and the review actions: edit the answer, approve, escalate, mark not applicable, mark wrong, save to the answer library.",
+      "operations": [
+        "approve_questionnaire_answer_accounts__account_id__security_questionnaires__questionnaire_id__questions__question_id__approve_post",
+        "escalate_questionnaire_question_accounts__account_id__security_questionnaires__questionnaire_id__questions__question_id__escalate_post",
+        "flag_questionnaire_answer_accounts__account_id__security_questionnaires__questionnaire_id__questions__question_id__mark_wrong_post",
+        "save_questionnaire_answer_to_library_accounts__account_id__security_questionnaires__questionnaire_id__questions__question_id__save_to_library_post",
+        "skip_questionnaire_question_accounts__account_id__security_questionnaires__questionnaire_id__questions__question_id__mark_skip_post",
+        "update_questionnaire_answer_accounts__account_id__security_questionnaires__questionnaire_id__questions__question_id__patch"
+      ],
+      "tiers": [
+        "write"
+      ]
+    },
+    {
+      "name": "CorrespondencePanel",
+      "file": "components/correspondence-panel.tsx",
+      "purpose": "What has been said to an account: list filtered by channel and person with Load more, the selected message, record one, import, and delete behind a confirmation.",
+      "operations": [
+        "delete_account_correspondence_accounts__account_id__correspondence__correspondence_id__delete",
+        "list_account_correspondence_accounts__account_id__correspondence_get",
+        "list_contacts_contacts_get"
+      ],
+      "tiers": [
+        "read",
+        "destructive"
+      ]
+    },
+    {
+      "name": "CorrespondenceForm",
+      "file": "components/correspondence-form.tsx",
+      "purpose": "Record one message, call or note against an account, dated when it happened, with an optional person at the account.",
+      "operations": [
+        "create_account_correspondence_accounts__account_id__correspondence_post",
+        "list_contacts_contacts_get"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "CorrespondenceImport",
+      "file": "components/correspondence-import.tsx",
+      "purpose": "Import a JSON batch of messages (partial success reported, external_id makes a re-run safe) or record one text file.",
+      "operations": [
+        "import_account_correspondence_accounts__account_id__correspondence_import_post",
+        "upload_account_correspondence_accounts__account_id__correspondence_upload_post"
+      ],
+      "tiers": [
+        "write"
+      ]
+    },
+    {
+      "name": "AccountBar",
+      "file": "components/account-bar.tsx",
+      "purpose": "Choose the account (company) the questionnaire and correspondence tabs work on; shows a name for an id that arrives in the URL.",
+      "operations": [
+        "get_company_companies__company_id__get",
+        "list_companies_companies_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "RecordDocumentsTab",
+      "file": "components/record-documents-tab.tsx",
+      "purpose": "The latest messages and questionnaires for the account behind a company, contact or deal; an extraDetailTabs entry for CompaniesScreen, ContactsScreen and DealsScreen.",
+      "operations": [
+        "get_contact_contacts__contact_id__get",
+        "list_account_correspondence_accounts__account_id__correspondence_get",
+        "list_security_questionnaires_accounts__account_id__security_questionnaires_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    }
+  ],
+  "screens": [
+    {
+      "component": "DocumentsScreen",
+      "path": "/documents",
+      "label": "Documents",
+      "icon": "FileText",
+      "group": "Documents",
+      "description": "Library, security questionnaires and account correspondence"
+    }
+  ],
+  "hooks": [],
+  "lib": [
+    {
+      "file": "lib/documents-types.ts",
+      "purpose": "Library, folder, questionnaire, question and correspondence shapes; the API's file types, channels and statuses; size, folder-name and import checks; the review-state helper."
+    },
+    {
+      "file": "lib/download.ts",
+      "purpose": "Save a raw-bytes response (an original Library file, a filled workbook) through the /api/g8 proxy as a download; the key stays on the server."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/organize-the-library.ts",
+      "title": "Create a folder and a text document, then list what is in it",
+      "when": "Seeding the Library from a script; nothing is sent to anyone."
+    },
+    {
+      "file": "recipes/log-account-correspondence.ts",
+      "title": "Import an account's messages so a re-run skips what is already there",
+      "when": "Bringing emails or call notes in from another system; external_id makes it re-runnable."
+    },
+    {
+      "file": "recipes/follow-a-questionnaire.ts",
+      "title": "Follow a security questionnaire to completion and list what needs review",
+      "when": "After uploading a questionnaire in the app; reads only, approves nothing."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "documents-scopes",
+      "description": "The key needs knowledge:read, knowledge:write and knowledge:delete for the Library, companies:read, companies:write and companies:delete for questionnaires and correspondence, and knowledge:run to upload a questionnaire (a billable operation separate from knowledge:write). The pickers need contacts:read.",
+      "where": "api",
+      "verify": "g8.api.me.describeCurrentKey() lists the scopes."
+    },
+    {
+      "id": "proxy-allowlist",
+      "description": "Add \"library\", \"accounts\", \"companies\" and \"contacts\" to allowedPrefixes in app/api/g8/[...path]/route.ts. The documents endpoints live under /library and /accounts, not /documents.",
+      "where": "app",
+      "verify": "The route file's allowedPrefixes contains them."
+    },
+    {
+      "id": "upload-size",
+      "description": "The /api/g8 proxy caps the whole request body at 5 MiB by default, while the Library accepts files up to 50 MB. The screen keeps every file, and every request of a multi-file upload (split into several), under that cap; to allow more, raise maxBodyBytes in the proxy route AND pass the same number as maxBytes to DocumentsScreen.",
+      "where": "app",
+      "verify": "The route file sets maxBodyBytes, and an upload near the limit succeeds."
+    },
+    {
+      "id": "answer-library",
+      "description": "Questionnaires are answered from your Library and policy documents. Upload your security policies and past answers first; an empty library gives empty or weak answers. Answering uses credits and a person confirms before it starts.",
+      "where": "app",
+      "verify": "The Library has the security documents the buyer's questions draw on."
+    }
+  ],
+  "scopes": [
+    "companies:delete",
+    "companies:read",
+    "companies:write",
+    "contacts:read",
+    "knowledge:delete",
+    "knowledge:read",
+    "knowledge:run",
+    "knowledge:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Which library",
+      "default": "The organization's (global) Library; the API's campaign and account libraries use different ids on read and write, so they are not offered",
+      "askHuman": false
+    },
+    {
+      "decision": "Where an upload lands",
+      "default": "The folder currently open, else the Library root; the person can change it",
+      "askHuman": false
+    },
+    {
+      "decision": "File size limit",
+      "default": "5 MiB, the proxy's default body limit",
+      "askHuman": false
+    },
+    {
+      "decision": "Uploading a questionnaire",
+      "default": "Never without a person confirming; it uses credits and the API publishes no price",
+      "askHuman": true
+    },
+    {
+      "decision": "Approving an answer",
+      "default": "A person reads it and approves; nothing is approved automatically",
+      "askHuman": true
+    },
+    {
+      "decision": "Message channel and direction",
+      "default": "None: a person chooses, because a wrong guess misplaces the message on the account timeline",
+      "askHuman": true
+    },
+    {
+      "decision": "Deleting",
+      "default": "Always confirmed; a deleted document, questionnaire or message cannot be brought back",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
+  }
+}

package/blocks/documents/components/account-bar.tsx

@@ -0,0 +1,48 @@
+"use client";
+
+/**
+ * AccountBar: choose the account (company) whose questionnaires or correspondence you are working on.
+ *
+ * SDK operations, in order:
+ *   1. listCompanies, through CompanyPicker                    read  find the company by name or domain
+ *   2. getCompany (GET /companies/{company_id})                read  the name of a company that arrives as an id in the URL (a shared link, a reload), so the picker shows a name, not a number
+ * The id is the screen's to keep (`?account=`); this only reports it. Nothing here is billable, external or destructive.
+ */
+
+import { useState } from "react";
+import { Label } from "@graph8/sdk/ui";
+import { CompanyPicker } from "@/g8/pickers/components/company-picker";
+import type { CompanyOption } from "@/g8/pickers/components/company-picker";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+
+export interface AccountBarProps {
+  /** The chosen company id, or null. */
+  accountId: number | null;
+  onChange: (companyId: number) => void;
+  className?: string;
+}
+
+interface CompanyRow { id?: number | null; name?: string | null; domain?: string | null; industry?: string | null }
+
+export function AccountBar({ accountId, onChange, className }: AccountBarProps) {
+  const [picked, setPicked] = useState<CompanyOption | null>(null);
+  const known = picked !== null && picked.id === accountId;
+  const company = useG8Query(
+    (signal) => g8Get<CompanyRow>(`/companies/${accountId}`, {}, { signal }).then((r) => r.data),
+    [accountId],
+    { enabled: accountId != null && !known, key: ["documents", "account", accountId ?? ""] },
+  );
+  let value: CompanyOption | null = known ? picked : null;
+  if (!value && accountId != null) {
+    const c = company.data;
+    if (c) value = { id: accountId, name: c.name || c.domain || `Company ${accountId}`, hint: [c.domain, c.industry].filter(Boolean).join(" · ") || undefined };
+    else if (company.error) value = { id: accountId, name: `Company ${accountId}` };
+  }
+  return (
+    <div className={className}>
+      <Label htmlFor="g8-ab-company" className="mb-1">Account</Label>
+      <CompanyPicker id="g8-ab-company" label="Account" value={value} onChange={(c) => { setPicked(c); onChange(c.id); }} />
+    </div>
+  );
+}

package/blocks/documents/components/correspondence-form.tsx

@@ -0,0 +1,95 @@
+"use client";
+
+/**
+ * CorrespondenceForm: record ONE message, call or note against an account.
+ *
+ * SDK operations, in order:
+ *   1. listContacts, through ContactPicker                                          read   find the person at the account (optional)
+ *   2. createAccountCorrespondence (POST /accounts/{account_id}/correspondence)     write  stores the record and indexes it so generated documents can read it
+ * `correspondence_date` is when it HAPPENED, not when it was recorded: generated documents read it as the relationship's
+ * timeline, so it is required and sent as the exact moment (never as a date alone). Channel and direction have no default:
+ * a wrong guess would put the message on the wrong side of the timeline. Nothing here is billable, external or destructive.
+ */
+
+import { useState } from "react";
+import { Button, Input, Label, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { ContactPicker } from "@/g8/pickers/components/contact-picker";
+import type { ContactOption } from "@/g8/pickers/components/contact-picker";
+import { CORRESPONDENCE_CHANNELS, DIRECTIONS } from "../lib/documents-types";
+import type { Correspondence } from "../lib/documents-types";
+
+export interface CorrespondenceFormProps {
+  accountId: number;
+  /** Pre-select the person (for example from a contact page). */
+  stakeholder?: ContactOption | null;
+  onSaved: (record: Correspondence) => void;
+  onCancel?: () => void;
+}
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm";
+
+export function CorrespondenceForm({ accountId, stakeholder, onSaved, onCancel }: CorrespondenceFormProps) {
+  const [channel, setChannel] = useState("");
+  const [direction, setDirection] = useState("");
+  const [when, setWhen] = useState("");
+  const [subject, setSubject] = useState("");
+  const [content, setContent] = useState("");
+  const [person, setPerson] = useState<ContactOption | null>(stakeholder ?? null);
+  const [externalId, setExternalId] = useState("");
+  const date = when ? new Date(when) : null;
+  const valid = channel !== "" && direction !== "" && content.trim() !== "" && date !== null && !Number.isNaN(date.getTime());
+
+  const save = useG8Mutation(
+    async (): Promise<Correspondence> => {
+      const body: Record<string, unknown> = { channel, direction, content: content.trim(), correspondence_date: date!.toISOString() };
+      if (subject.trim()) body.subject = subject.trim();
+      if (person) body.stakeholder_id = String(person.id);
+      if (externalId.trim()) body.external_id = externalId.trim();
+      return (await g8Post<Correspondence>(`/accounts/${encodeURIComponent(String(accountId))}/correspondence`, body)).data;
+    },
+    { onSuccess: onSaved, invalidates: [["documents", "correspondence"]] },
+  );
+
+  return (
+    <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (valid) void save.mutate(undefined); }}>
+      <div className="grid gap-3 sm:grid-cols-2">
+        <div>
+          <Label htmlFor="g8-dc-channel" className="mb-1">Channel</Label>
+          <select id="g8-dc-channel" className={SELECT} value={channel} onChange={(e) => setChannel(e.target.value)}>
+            <option value="">Choose a channel</option>
+            {CORRESPONDENCE_CHANNELS.map((c) => <option key={c.value} value={c.value}>{c.label}</option>)}
+          </select>
+        </div>
+        <div>
+          <Label htmlFor="g8-dc-direction" className="mb-1">Direction</Label>
+          <select id="g8-dc-direction" className={SELECT} value={direction} onChange={(e) => setDirection(e.target.value)}>
+            <option value="">Choose a direction</option>
+            {DIRECTIONS.map((d) => <option key={d.value} value={d.value}>{d.label}</option>)}
+          </select>
+        </div>
+      </div>
+      <div>
+        <Label htmlFor="g8-dc-when" className="mb-1">When it happened</Label>
+        <Input id="g8-dc-when" type="datetime-local" value={when} onChange={(e) => setWhen(e.target.value)} />
+      </div>
+      <div><Label htmlFor="g8-dc-subject" className="mb-1">Subject (optional)</Label><Input id="g8-dc-subject" value={subject} onChange={(e) => setSubject(e.target.value)} /></div>
+      <div><Label htmlFor="g8-dc-content" className="mb-1">What was said</Label><Textarea id="g8-dc-content" rows={8} value={content} onChange={(e) => setContent(e.target.value)} /></div>
+      <div>
+        <Label htmlFor="g8-dc-person" className="mb-1">Person at the account (optional)</Label>
+        <div className="flex items-center gap-2">
+          <ContactPicker id="g8-dc-person" label="Person" value={person} onChange={setPerson} />
+          {person ? <Button type="button" variant="ghost" size="sm" onClick={() => setPerson(null)}>Clear</Button> : null}
+        </div>
+      </div>
+      <div><Label htmlFor="g8-dc-ext" className="mb-1">Your id for it (optional)</Label><Input id="g8-dc-ext" value={externalId} onChange={(e) => setExternalId(e.target.value)} /></div>
+      {save.error ? <ApiError error={save.error} title="Could not record the message" /> : null}
+      <div className="flex gap-2">
+        <Button type="submit" loading={save.loading} disabled={!valid}>Record message</Button>
+        {onCancel ? <Button type="button" variant="outline" onClick={onCancel}>Cancel</Button> : null}
+      </div>
+    </form>
+  );
+}