fix(sharing): show a guardian the controls the routes accept (#939)

useRecordCapabilities answers per section now. canWriteDomain and
canManageDomain read the two lists the account payload publishes; in
one's own record they are always true, and under a refused, pending or
unproven context always false. canManage becomes the coarse switch,
true when any section is manageable, and is what the banner and the
navigation read.

Every add, edit and delete control names its own section: labs, mind,
profile, illness, cycle, medications, measurements, documents. Creates
that a WRITE route answers (visits, practitioners) ask canWriteDomain.
The generic delete button, the selection bar, the capture picker, the
dashboard quick entry and the bottom nav take the section from their
callers. Controls whose routes resolve the caller rather than the
record (settings shortcuts, chart overlay preferences, custom metrics,
the Today rail, OCR, efficacy targets, credential tabs) ask for the
caller's own record instead, and the customise-shortcut guard now
requires that shape.

The vault has no delegated write route, so its controls stay withheld
under every grant, and the documents page says so in one sentence
where the upload control would be, in all seven locales.

src/components/documents/document-detail-sheet.tsx

@@ -373,7 +373,8 @@ export function DocumentDetailSheet({
       (fact) => fact.factType === "OBSERVATION" && fact.status === "APPROVED",
     ).length ?? 0;
   const { user } = useAuth();
-  const { canManage } = useRecordCapabilities();
+  const { canManageDomain } = useRecordCapabilities();
+  const canManageDocuments = canManageDomain("documents");
   const labsModuleEnabled = user?.modules?.labs !== false;
 
   const episodes = useIllnessEpisodes(true);
@@ -387,14 +388,14 @@ export function DocumentDetailSheet({
   // document reads behind this sheet are delegable; the AI verbs above them are
   // not, and both of these routes stay on the caller's own authentication. A
   // delegate would fire two queries that must 403 in order to compute an
-  // affordance every branch below already withholds on `canManage`.
+  // affordance every branch below already withholds on `canManageDocuments`.
   const capability = useDocumentAiCapability(
-    canManage && open && documentId !== null,
+    canManageDocuments && open && documentId !== null,
   );
   // When auto-read is ON, reading happens automatically on upload — the manual
   // per-document AI action row is redundant and collapses away.
   const autoRead = useDocumentsAutoAiRead(
-    canManage && open && documentId !== null,
+    canManageDocuments && open && documentId !== null,
   );
   const suggest = useSuggestDetails();
   const summary = useDocumentSummary();
@@ -709,7 +710,7 @@ export function DocumentDetailSheet({
                   owner's alone. Inside somebody else's record the sheet reads
                   the document and offers the download, and the leading slot
                   simply has nothing in it. */}
-              {canManage ? (
+              {canManageDocuments ? (
                 <Button
                   variant="ghost"
                   className="text-destructive hover:text-destructive hover:bg-destructive/10"
@@ -751,7 +752,7 @@ export function DocumentDetailSheet({
                     </span>
                   </Button>
                 ) : null}
-                {canManage && (
+                {canManageDocuments && (
                   <Button
                     variant="outline"
                     onClick={() => setShareOpen(true)}
@@ -829,7 +830,7 @@ export function DocumentDetailSheet({
               // The stored summary is read; generating one writes to the
               // owner's record, so a delegate reads what is there and has no
               // generate control.
-              canGenerate={canManage}
+              canGenerate={canManageDocuments}
               summaryState={doc.summaryState}
               generatedAtLabel={
                 doc.summaryGeneratedAt
@@ -842,7 +843,7 @@ export function DocumentDetailSheet({
               onGenerate={generateStoredSummary}
             />
 
-            {canManage && (
+            {canManageDocuments && (
               <DocumentAiSection
                 aiEnabled={aiEnabled}
                 autoReadEnabled={autoReadEnabled}
@@ -906,7 +907,7 @@ export function DocumentDetailSheet({
                     maxLength={200}
                     placeholder={t("documents.detail.titlePlaceholder")}
                   />
-                ) : !canManage ? (
+                ) : !canManageDocuments ? (
                   <p
                     id="document-title-input"
                     className={cn(
@@ -952,7 +953,7 @@ export function DocumentDetailSheet({
                       without accepting a change is the honest rendering. */}
                   <Select
                     value={doc.kind}
-                    disabled={!canManage}
+                    disabled={!canManageDocuments}
                     onValueChange={(value) =>
                       patch.mutate({ kind: value as InboundDocumentKindValue })
                     }
@@ -975,7 +976,7 @@ export function DocumentDetailSheet({
                   </Label>
                   <DateField
                     id="document-date-field"
-                    disabled={!canManage}
+                    disabled={!canManageDocuments}
                     value={doc.documentDate ?? ""}
                     onChange={(value) =>
                       patch.mutate({
@@ -1006,7 +1007,7 @@ export function DocumentDetailSheet({
                       {t("documents.detail.noConditions")}
                     </span>
                   ) : null}
-                  {canManage && (episodes.data?.length ?? 0) > 0 ? (
+                  {canManageDocuments && (episodes.data?.length ?? 0) > 0 ? (
                     <Popover>
                       <PopoverTrigger asChild>
                         <Button
@@ -1058,7 +1059,7 @@ export function DocumentDetailSheet({
                 alreadyLinked={
                   doc.encounterLinks.length > 0 && pickedEncounterId === null
                 }
-                disabled={!canManage}
+                disabled={!canManageDocuments}
                 value={pickedEncounterId}
                 onChange={setSuggestedEncounter}
               />
@@ -1069,7 +1070,7 @@ export function DocumentDetailSheet({
                 <VaccinationDocumentSuggestion
                   anchor={doc.reportDate ?? doc.documentDate}
                   documentId={doc.id}
-                  disabled={!canManage}
+                  disabled={!canManageDocuments}
                 />
               ) : null}
 
@@ -1111,7 +1112,7 @@ export function DocumentDetailSheet({
                   values" over its stored text — never a re-upload. */}
               <DocumentFactsSection
                 doc={doc}
-                canManage={canManage}
+                canManage={canManageDocuments}
                 aiEnabled={aiEnabled}
                 labsModuleEnabled={labsModuleEnabled}
               />

src/components/documents/documents-view.tsx

@@ -241,8 +241,10 @@ export function DocumentsView() {
   // v1.36.x — uploading a document, filing it, sharing it and asking the AI
   // about it are none of them delegated verbs. Inside somebody else's record
   // the vault reads and nothing more: no upload path, no selection, no bulk
-  // bar, no corpus backfill.
-  const { canManage, inSharedRecord, sections } = useRecordCapabilities();
+  // bar, no corpus backfill. `canManageDomain("documents")` says so from the
+  // server's table, and answers false under every grant today.
+  const { canManageDomain, inSharedRecord, sections } = useRecordCapabilities();
+  const canManageDocuments = canManageDomain("documents");
   const router = useRouter();
   const pathname = usePathname();
   const searchParams = useSearchParams();
@@ -424,7 +426,9 @@ export function DocumentsView() {
     },
     [episodeIdFilter, t],
   );
-  const { dropActive } = usePageFileDrop(canManage ? enqueueFiles : undefined);
+  const { dropActive } = usePageFileDrop(
+    canManageDocuments ? enqueueFiles : undefined,
+  );
 
   const episodes = useIllnessEpisodes(
     true,
@@ -439,7 +443,7 @@ export function DocumentsView() {
   const contentIndex = usage.data?.contentIndex;
   const canIndexContent = contentIndex?.enabled ?? false;
   const showIndexAll =
-    canManage &&
+    canManageDocuments &&
     canIndexContent &&
     contentIndex !== undefined &&
     contentIndex.totalCount > 0 &&
@@ -872,7 +876,7 @@ export function DocumentsView() {
         title={t("documents.title")}
         description={t("documents.subtitle")}
         actions={
-          canManage ? (
+          canManageDocuments ? (
             <Button
               className="min-h-11 sm:min-h-9"
               onClick={() => uploadInputRef.current?.click()}
@@ -884,13 +888,23 @@ export function DocumentsView() {
         }
       />
 
-      {canManage && (
+      {canManageDocuments && (
         <UploadZone
           usage={usage.data}
           inputRef={uploadInputRef}
           onFiles={enqueueFiles}
         />
       )}
+      {inSharedRecord && !canManageDocuments && (
+        // Where the upload zone would be: the one empty space a person acting
+        // for somebody else would otherwise search a control in.
+        <p
+          className="text-muted-foreground text-sm"
+          data-slot="documents-owner-only"
+        >
+          {t("documents.ownerOnlyUpload")}
+        </p>
+      )}
 
       <DocumentFilterBar
         searchValue={searchDraft}
@@ -932,7 +946,7 @@ export function DocumentsView() {
           description={t("documents.empty.description")}
           ctaSize="lg"
           action={
-            canManage ? (
+            canManageDocuments ? (
               <Button
                 className="min-h-11 sm:min-h-9"
                 onClick={() => uploadInputRef.current?.click()}
@@ -963,9 +977,9 @@ export function DocumentsView() {
           isFetchingNextPage={list.isFetchingNextPage}
           onLoadMore={() => void list.fetchNextPage()}
           selectedIds={selectedIds}
-          onToggleSelected={canManage ? toggleSelected : undefined}
+          onToggleSelected={canManageDocuments ? toggleSelected : undefined}
           onOpen={openDetail}
-          onDelete={canManage ? (id) => deleteBulk([id]) : undefined}
+          onDelete={canManageDocuments ? (id) => deleteBulk([id]) : undefined}
           highlightId={upload.highlightId}
           onPrefetch={prefetchDetail}
         />
@@ -979,7 +993,7 @@ export function DocumentsView() {
         contentIndexEnabled={usage.data?.contentIndex.enabled}
       />
 
-      {canManage && selectedIds.size > 0 ? (
+      {canManageDocuments && selectedIds.size > 0 ? (
         <DocumentBulkBar
           selectedCount={selectedIds.size}
           episodes={(episodes.data ?? []).map((e) => ({

src/components/documents/episode-documents-card.tsx

@@ -49,10 +49,11 @@ export function EpisodeDocumentsCard({ episodeId }: { episodeId: string }) {
   const { user } = useAuth();
   // Linking a document to an episode writes through
   // `POST /api/documents/inbound/bulk`, the same endpoint the vault gates on
-  // `canManage` throughout. The episode side of the same link had no gate at
+  // `canManageDocuments` throughout. The episode side of the same link had no gate at
   // all, so the vault refused what this card offered. Reading the linked
   // documents stays: the list rows and "show all" are pure navigation.
-  const { canManage } = useRecordCapabilities();
+  const { canManageDomain } = useRecordCapabilities();
+  const canManageDocuments = canManageDomain("documents");
   const [pickerOpen, setPickerOpen] = useState(false);
 
   const moduleEnabled = user?.modules?.inboundDocuments === true;
@@ -146,7 +147,7 @@ export function EpisodeDocumentsCard({ episodeId }: { episodeId: string }) {
           )}
 
           <div className="flex flex-wrap items-center gap-1.5">
-            {canManage ? (
+            {canManageDocuments ? (
               <>
                 <Button
                   variant="outline"
@@ -158,7 +159,7 @@ export function EpisodeDocumentsCard({ episodeId }: { episodeId: string }) {
                 </Button>
                 {/* The upload affordance is a deep link into the vault with
                     this episode pre-filtered. The vault's own upload control
-                    is `canManage`-gated, so an ungated link here would send a
+                    is `canManageDocuments`-gated, so an ungated link here would send a
                     delegate to a page with nothing to press. */}
                 <Button asChild variant="outline" size="sm">
                   <Link href={vaultHref}>
@@ -184,7 +185,7 @@ export function EpisodeDocumentsCard({ episodeId }: { episodeId: string }) {
         </CardContent>
       </Card>
 
-      {canManage ? (
+      {canManageDocuments ? (
         <DocumentLinkPicker
           episodeId={episodeId}
           open={pickerOpen}