@agent-native/core 0.152.0 → 0.153.0

package/corpus/templates/plan/.agents/skills/turn-into-app/references/spreadsheet-source.md

@@ -0,0 +1,148 @@
+# Spreadsheet source review
+
+Use this reference after a workbook upload or Google Sheets link is supplied to
+`/turn-into-app`. It defines the bounded review contract before app creation.
+
+## 1. Establish the source boundary
+
+Record the source before interpreting it:
+
+| Field        | Record                                                                            |
+| ------------ | --------------------------------------------------------------------------------- |
+| Source kind  | `xlsx`, `xls`, `csv`, or Google Sheets URL                                        |
+| Provenance   | Original file name or spreadsheet ID and URL; never credentials or workbook bytes |
+| Access       | Upload preview, authenticated provider read, or unavailable                       |
+| Coverage     | Worksheet names, selected range(s), row/column bounds, and sample counts          |
+| Completeness | Complete within the requested bound, partial, truncated, unreadable, or empty     |
+| Refresh      | One-time snapshot or live refreshable source                                      |
+
+For an uploaded XLS/XLSX file, the framework preview contains worksheet names,
+dimensions, and representative displayed values within bounds. It does not
+currently preserve cell fills or font colors in that text preview. Treat the
+original workbook as the formatting authority only when a tool actually returns
+cell formatting metadata. Never describe a text-only upload as style-verified.
+
+For a Google Sheets URL:
+
+1. Parse the spreadsheet ID and preserve the original URL as provenance.
+2. Use the authenticated `google_drive` provider path. Inspect
+   `provider-api-catalog` first, use `provider-api-docs` if the endpoint or
+   fields are uncertain, and then call `provider-api-request`.
+3. Read spreadsheet metadata and only bounded worksheet/range data. Request
+   formatting metadata when the I/O decision depends on colors, including
+   `userEnteredFormat.backgroundColor` and
+   `userEnteredFormat.textFormat.foregroundColor` where the provider supports
+   it. Do not use a public export URL to bypass access.
+4. Preserve the spreadsheet ID, worksheet title, A1 range, account/connection
+   choice without secrets, row limits, and refresh behavior in the brief.
+
+Keep provider responses bounded. For large sheets, stage or save the response
+and reduce it with the available dataset/code tools. A failed page, truncated
+response, or unavailable connection is not an empty sheet.
+
+## 2. Infer cells and ranges, then show the evidence
+
+Classify source material into three separate buckets. Include representative
+cell addresses or ranges and the evidence behind each classification.
+
+| Bucket             | Default signal                                                                                                     | App treatment                                                          |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Inputs             | Yellow cell background, editable assumptions, user-entered constants, or labels such as `assumption` / `driver`    | Editable controls or bounded source parameters                         |
+| Outputs            | Blue text, formula-derived result cells, summary blocks, or labels such as `forecast` / `recommendation`           | Read-only results, charts, recommendations, exports, or review actions |
+| Static historicals | Black text used intentionally for prior-period/source records, raw rows, or labels such as `actual` / `historical` | Read-only context; never turn into editable inputs by default          |
+
+These are conventions, not permission to guess. A default black font with no
+explicit style metadata is not enough to label a range as historical. Resolve
+conflicts using labels, formulas, neighboring headers, repeated patterns, and
+the user's stated goal. If the evidence still conflicts, lower confidence and
+ask the user to confirm the proposed mapping.
+
+Keep source cells and app behavior distinct:
+
+- `Source inputs` are the workbook cells or ranges the user is expected to
+  change or refresh.
+- `Source outputs` are the workbook cells or ranges the source already derives
+  or presents.
+- `Static historicals` are context the app may filter, compare, or summarize,
+  but should not edit.
+- `App outputs` are the new app's visible results, saved records, exports,
+  alerts, or downstream handoffs. Do not invent these until the repeatable job
+  or user confirmation makes them clear.
+
+## 3. Offer candidate apps, not a tab dump
+
+Group related worksheets into candidate repeatable jobs. A candidate should
+have a recognizable user, trigger, inputs, transformation or judgment, and
+outputs. Utility tabs such as lookups, raw imports, instructions, pivots, and
+calculation helpers can support a candidate without becoming destinations.
+
+Present a compact Q&A review with multi-select options. In generated app code,
+use `askUserQuestion` from `@agent-native/core/client/agent-chat` with
+`allowMultiple: true`, stable candidate IDs as option values, and
+`allowFreeText: true` for corrections. It renders inline in the agent panel;
+do not build a custom modal. Each option should fit in a scannable row or
+choice card:
+
+```text
+Candidate: Pipeline forecast
+Uses: Assumptions, Historical Pipeline, Forecast
+Inputs: yellow assumptions in Assumptions!B4:B12 (high confidence)
+Outputs: blue forecast summary in Forecast!B3:H10 (medium confidence)
+Historical context: Historical Pipeline!A1:K500
+Question: Confirm that forecast assumptions should be editable?
+```
+
+Mark the strongest recommendation with `recommended: true`, but do not silently
+select it. Let the user select none, one, or several candidates, correct a
+proposed tab/range, or answer the unresolved question. Keep each question to
+2-4 grouped candidate jobs; for a larger workbook, group related tabs into
+jobs rather than showing a tab dump or asking a separate question for every
+worksheet. If there is only one high-confidence candidate, keep the review
+compact and ask for confirmation only when the I/O mapping or source access is
+unclear.
+
+When several candidates are selected, pass a stable candidate ID, display name,
+source worksheet/ranges, I/O mapping, confidence, and confirmation status for
+each. The generated app should expose them as separate named left-navigation
+destinations or tabs, not merge them into an opaque dashboard and not create a
+separate workspace app for every worksheet.
+
+## 4. Confirm before building or publishing
+
+The confirmation view is a source-integrity checkpoint, not a product-design
+questionnaire. Show:
+
+- the source file or spreadsheet ID and snapshot/live choice;
+- selected candidate destinations and their source tabs/ranges;
+- editable inputs, read-only outputs, and static historical context;
+- the evidence and confidence for each mapping;
+- truncation, unreadable, missing-connection, and refresh limitations;
+- the app outputs/actions that will be created.
+
+Use clear actions such as `Confirm and build`, `Edit mapping`, and `Use a
+different source`. If the host has a structured question or multi-select UI,
+use it. Otherwise, ask one concise assistant message that presents the same
+options and requires an explicit confirmation/correction before handoff.
+
+After confirmation, the online host may call
+`start-workspace-app-creation`; the Builder run itself remains autonomous and
+must record any remaining non-blocking assumptions. In a local generated app,
+persist the confirmation state in SQL/application state and keep the user on
+the review surface while the agent builds. Never claim a full import, live
+refresh, or output write until the corresponding source/action has succeeded.
+
+## 5. Failure and recovery states
+
+Keep these states distinct in the review and in the handoff:
+
+- `unreadable` - parser/provider could not read the source;
+- `partial` - only some worksheets, ranges, rows, or pages were read;
+- `truncated` - the bounded preview ended before full coverage;
+- `empty` - the requested readable range contains no values;
+- `not-connected` - authenticated Google access is required but unavailable;
+- `confirmed` - the user approved the candidate and I/O mapping.
+
+For unreadable or not-connected sources, request a CSV/XLSX export or the
+required connection. For partial or truncated sources, continue only with a
+clearly bounded snapshot or ask for a narrower range. Do not coerce any of
+these states into a successful empty source.

package/corpus/templates/plan/.agents/skills/workspace-conventions/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: workspace-conventions
+description: >-
+  Shared conventions for a multi-app Agent Native workspace: finding
+  version-matched framework docs and source, shared vs app-owned code, file and
+  blob storage, env and secrets, agent scratch files, and Dispatch Resources.
+  Use when working across workspace apps, storing files or credentials, or
+  looking up framework APIs.
+scope: dev
+---
+
+# Workspace Conventions
+
+The long-form detail behind the workspace `AGENTS.md` core rules. Read this
+before adding shared code, storing files or secrets, creating workspace
+resources, or looking up framework APIs.
+
+## Framework Docs Lookup
+
+Read `agent-native-docs` for the lookup workflow (`framework-search` first, then
+the focused `docs-search` / `source-search` readers, and the `rg` fallback).
+
+The workspace-specific slugs it does not list are `workspace` and
+`multi-app-workspace`. Feature flags and other specialized workflows are
+optional; read their skill only when the app uses them. Use package docs for framework APIs,
+the package corpus for reusable framework/template patterns, and this
+`AGENTS.md` plus `.agents/skills/` for workspace-specific conventions.
+
+Before building common workspace or agent UI, read `agent-native-toolkit` to
+inventory existing public kits and installed package seams. Read
+`customizing-agent-native` before adapting shared UI. Use the supported
+ladder: configure → compose → eject the smallest unit → propose a shared seam.
+Preview before `--apply`, commit `agent-native.ejections.json`, and never edit
+`node_modules` or eject protected runtime contracts.
+
+## Shared Conventions
+
+- All AI/LLM behavior goes through the app's agent chat. UI and server code
+  must not call model providers, AI SDK `generateText()` / `streamText()`, or
+  other inline LLM APIs directly. Use `sendToAgentChat()` for local app-agent
+  work, including hidden `context` and `submit: false` prefill/review flows.
+  Keep actions deterministic and focused. If a workflow is framed as research,
+  analysis, generation, recommendation, or synthesis, let the agent
+  orchestrate provider/data actions in the open AgentSidebar instead of hiding
+  the work in one opaque action or a separate follow-up textbox.
+  Only use `useAgentChatContext`, `setAgentChatContextItem`,
+  `listAgentChatContext`, `removeAgentChatContextItem`, and
+  `clearAgentChatContext` when UI needs two-way sync with staged context chips.
+  Read `.agents/skills/delegate-to-agent/SKILL.md` before building agent-driven
+  UI or "AI" features.
+- Put shared code in `packages/shared` only when multiple apps need it.
+- Keep app-specific screens, actions, state, and skills inside `apps/<app>`.
+- SQL is for structured records, metadata, references, and searchable text. Store
+  large files/blob payloads (base64, `data:` URLs, images, video/audio, PDFs,
+  ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
+  storage and persist only URLs, ids, or handles.
+- Store shared runtime configuration in the workspace root `.env`; use
+  `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
+  tokens, webhook URLs, signing secrets, private Builder/internal data, customer
+  data, or credential-looking literals in source, docs, prompts, fixtures,
+  application state, action responses, or generated app content. Use
+  secrets/OAuth/runtime configuration and obvious placeholders in examples.
+- Each app deploys its own `/*` page function, and that function ships whatever
+  the app's server bundle depends on — including a dependency only a background
+  job uses. Before an app takes on a heavy runtime (headless browser, ffmpeg,
+  media processing, ML), read `.agents/skills/performance/SKILL.md` §9 and keep
+  that work in a background function or job. A dependency belonging to one app
+  does not belong in `packages/shared`.
+- Prefer framework defaults until the workspace has a real custom rule,
+  component, plugin, action, or skill to share.
+- Keep the Workspace files view for user-authored or user-requested resources.
+  Agents may create hidden `agent_scratch` resources for temporary working
+  notes, scripts, task plans, or intermediate outputs, but should promote them
+  to normal workspace visibility only when the user explicitly asks to keep or
+  manage the file.
+- Runtime-editable global resources can be managed from Dispatch Resources.
+  Use `AGENTS.md` or `instructions/<slug>.md` for always-on guardrails,
+  `skills/<slug>/SKILL.md` for workspace skills, `context/<slug>.md` for
+  personas/positioning/messaging/company facts/brand guidelines, and
+  `agents/<slug>.md` for custom agent profiles. Scope them to All apps when
+  every workspace app should inherit them. All-app resources are inherited at
+  runtime; do not copy or sync them into individual apps.
+
+## Related Skills
+
+- **adding-workspace-apps** — Creating and mounting a new app under `apps/`.
+- **agent-native-docs** — The full docs and source-corpus lookup workflow.
+- **agent-native-toolkit** — Inventory of shared workspace and agent UI.
+- **customizing-agent-native** — The configure → compose → eject ladder.
+- **delegate-to-agent** — Routing every AI feature through the agent chat.
+- **performance** — Load cost, and (§9) cold-start artifact size per app.
+- **secrets** — Registering API keys and service credentials.
+- **storing-data** — Where structured data and large payloads belong.

package/corpus/templates/plan/actions/delete-plan-comment.ts

@@ -5,6 +5,7 @@ import {
   assertAccess,
   currentAccess,
   resolveAccess,
+  roleSatisfies,
 } from "@agent-native/core/sharing";
 import { and, eq, inArray, isNull } from "drizzle-orm";
 import { z } from "zod";
@@ -131,6 +132,11 @@ export default defineAction({
     const requester = normalizeEmail(commentRequestEmail);
     const author = normalizeEmail(existing.authorEmail);
     const isAuthor = Boolean(requester && author && requester === author);
+    if (!roleSatisfies(access.role, "commenter")) {
+      throw new ForbiddenError(
+        "Commenting on this plan requires commenter access or higher.",
+      );
+    }
     if (!isAuthor) {
       try {
         await assertAccess(

package/corpus/templates/plan/actions/reply-to-plan-comment.ts

@@ -7,6 +7,7 @@ import {
   ForbiddenError,
   currentAccess,
   resolveAccess,
+  roleSatisfies,
 } from "@agent-native/core/sharing";
 import { and, eq, isNull } from "drizzle-orm";
 import { z } from "zod";
@@ -88,7 +89,7 @@ export default defineAction({
       );
     }
 
-    // Viewer-level access is sufficient for commenting (mirrors update-visual-plan).
+    // Commenter-level access is sufficient for commenting.
     const access = await resolveAccess(
       "plan",
       args.planId,
@@ -98,6 +99,11 @@ export default defineAction({
     if ((access.resource as typeof schema.plans.$inferSelect).deletedAt) {
       throw new ForbiddenError(`Plan ${args.planId} not found`);
     }
+    if (!roleSatisfies(access.role, "commenter")) {
+      throw new ForbiddenError(
+        "Commenting on this plan requires commenter access or higher.",
+      );
+    }
 
     const db = getDb();
     const now = nowIso();

package/corpus/templates/plan/actions/resolve-plan-comment.ts

@@ -7,6 +7,7 @@ import {
   ForbiddenError,
   currentAccess,
   resolveAccess,
+  roleSatisfies,
 } from "@agent-native/core/sharing";
 import { and, eq, isNull } from "drizzle-orm";
 import { z } from "zod";
@@ -126,7 +127,7 @@ export default defineAction({
       );
     }
 
-    // Viewer-level access is sufficient for status changes (mirrors update-visual-plan).
+    // Commenter-level access is sufficient for status changes.
     const access = await resolveAccess(
       "plan",
       args.planId,
@@ -136,6 +137,11 @@ export default defineAction({
     if ((access.resource as typeof schema.plans.$inferSelect).deletedAt) {
       throw new ForbiddenError(`Plan ${args.planId} not found`);
     }
+    if (!roleSatisfies(access.role, "commenter")) {
+      throw new ForbiddenError(
+        "Commenting on this plan requires commenter access or higher.",
+      );
+    }
 
     const db = getDb();
     const now = nowIso();

package/corpus/templates/plan/actions/update-visual-plan.ts

@@ -8,6 +8,7 @@ import {
   ForbiddenError,
   currentAccess,
   resolveAccess,
+  roleSatisfies,
 } from "@agent-native/core/sharing";
 import { and, eq, inArray, isNull } from "drizzle-orm";
 import { z } from "zod";
@@ -661,6 +662,11 @@ export default defineAction({
       if ((access.resource as typeof schema.plans.$inferSelect).deletedAt) {
         throw new ForbiddenError(`Plan ${args.planId} not found`);
       }
+      if (!roleSatisfies(access.role, "commenter")) {
+        throw new ForbiddenError(
+          "Commenting on this plan requires commenter access or higher.",
+        );
+      }
     } else {
       await assertPlanEditor(args.planId);
     }

package/corpus/templates/plan/app/hooks/use-plans.ts

@@ -362,7 +362,7 @@ export type PlanAccessStatusResponse = {
   signedIn: boolean;
   viewerEmail: string | null;
   viewerName: string | null;
-  role: "owner" | "viewer" | "editor" | "admin" | null;
+  role: "owner" | "viewer" | "commenter" | "editor" | "admin" | null;
   orgId: string | null;
   orgName: string | null;
   visibility: "private" | "org" | "public" | null;

package/corpus/templates/plan/app/pages/PlansPage.tsx

@@ -1786,7 +1786,7 @@ function cropFeedbackScreenshot(input: {
   return output.toDataURL("image/png");
 }
 
-type PlanAccessRole = "owner" | "viewer" | "editor" | "admin";
+type PlanAccessRole = "owner" | "viewer" | "commenter" | "editor" | "admin";
 
 /**
  * Status options available in the reviewer approval workflow.
@@ -1965,6 +1965,15 @@ export function canEditPlanContentRole(role?: PlanAccessRole | null) {
   return role === "owner" || role === "admin" || role === "editor";
 }
 
+export function canCommentPlanRole(role?: PlanAccessRole | null) {
+  return (
+    role === "owner" ||
+    role === "commenter" ||
+    role === "admin" ||
+    role === "editor"
+  );
+}
+
 export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
   const t = useT();
   const params = useParams<{ id?: string }>();
@@ -2403,6 +2412,8 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
       canEditPlanContentRole(effectivePlanAccessRole));
   const canManagePlan =
     !localPlanMode && canEditPlanContentRole(effectivePlanAccessRole);
+  const canCommentPlan =
+    localPlanMode || canCommentPlanRole(effectivePlanAccessRole);
   const canDeleteCurrentPlan =
     !localPlanMode && effectivePlanAccessRole === "owner";
   const currentPlanDeleteTarget = useMemo<DeletePlanTarget | null>(() => {
@@ -2428,9 +2439,7 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
     Boolean(bundle) &&
     effectivePlanVisibility === "public" &&
     !canManagePlan;
-  const canResolveCommentThreads = Boolean(
-    bundle && (localPlanMode || session || canEditPlanContent),
-  );
+  const canResolveCommentThreads = Boolean(bundle && canCommentPlan);
   const defaultInlineCommentDraft = useMemo<CommentDraft>(() => {
     return defaultInlineCommentDraftForPlanContext({
       planKind: bundle?.plan.kind,
@@ -2534,6 +2543,7 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
   );
   const canDeletePlanComment = useCallback(
     (comment: { authorEmail?: string | null }) => {
+      if (!canCommentPlan) return false;
       if (canManagePlan) return true;
       const currentEmail = normalizeCommentEmail(collabUser?.email);
       const authorEmail = normalizeCommentEmail(comment.authorEmail);
@@ -2544,7 +2554,7 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
         (!currentEmail || isLocalCurrentUserEmail(currentEmail))
       );
     },
-    [canManagePlan, collabUser?.email],
+    [canCommentPlan, canManagePlan, collabUser?.email],
   );
   const canDeleteCommentThread = useCallback(
     (thread: CommentThread) => canDeletePlanComment(thread.root),
@@ -3782,12 +3792,13 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
   };
 
   const startCommenting = useCallback(() => {
+    if (!canCommentPlan) return;
     setCanvasMarkupMode("none");
     setActiveAnnotation(null);
     setAnnotationsOpen(false);
     setCommentVisibility("open");
     setAnnotateMode(true);
-  }, []);
+  }, [canCommentPlan]);
 
   const selectReviewMode = (mode: CanvasMarkupMode) => {
     preservePlanReaderScroll(() => {
@@ -3929,6 +3940,7 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
 
   const openNativeSelectionComment = useCallback(
     (selectionComment: NativeSelectionComment) => {
+      if (!canCommentPlan) return;
       documentStateRef.current = readNativeDocumentState();
       setCanvasMarkupMode("none");
       setActiveAnnotation(null);
@@ -3940,11 +3952,11 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
       setNativeSelectionComment(null);
       window.getSelection()?.removeAllRanges();
     },
-    [readNativeDocumentState],
+    [canCommentPlan, readNativeDocumentState],
   );
 
   const beginNativeSelectionComment = () => {
-    if (!nativeSelectionComment) return;
+    if (!canCommentPlan || !nativeSelectionComment) return;
     openNativeSelectionComment(nativeSelectionComment);
   };
 
@@ -3989,6 +4001,7 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
   };
 
   const handleNativeReaderPointerUp = (event: PointerEvent<HTMLDivElement>) => {
+    if (!canCommentPlan) return;
     if (event.button !== 0) return;
     const target = event.target as HTMLElement;
     if (target.closest("[data-plan-interactive]")) return;
@@ -4509,6 +4522,7 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
     localBridgeCommentPending;
 
   const submitInlineComment = async (draft: CommentDraft) => {
+    if (!canCommentPlan) return;
     if (!bundle || !pendingAnnotation || !selectedPlanQueryKey) return;
     // Capture the current position before clearing (used to restore on failure).
     const capturedPosition = inlineCommentPosition;
@@ -4606,6 +4620,7 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
     annotation: RuntimeAnnotation,
     message: string,
   ) => {
+    if (!canCommentPlan) return;
     if (!bundle) return;
     const anchor: PlanAnnotationAnchor = {
       ...annotation.anchor,
@@ -4643,6 +4658,9 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
     threadRootId: string,
     message: string,
   ) => {
+    if (!canCommentPlan) {
+      throw new Error("Commenter access is required to reply to a comment.");
+    }
     if (!bundle || !selectedPlanQueryKey) return;
     const thread = commentThreads.find((item) => item.id === threadRootId);
     if (!thread) {
@@ -5587,7 +5605,7 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
                       }}
                     />
                   </div>
-                  {nativeSelectionComment && (
+                  {canCommentPlan && nativeSelectionComment && (
                     <div
                       className="absolute z-30"
                       style={{
@@ -5666,7 +5684,7 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
                   )}
                 />
               )}
-              {pendingAnnotation && inlineCommentPosition && (
+              {canCommentPlan && pendingAnnotation && inlineCommentPosition && (
                 <>
                   {pendingMarkerPlacement?.clip ? (
                     <div
@@ -5711,6 +5729,7 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
                   position={activeAnnotation.position}
                   isPending={commentWritePending}
                   pendingAuthor={pendingCommentAuthor}
+                  canComment={canCommentPlan}
                   canEditRootComment={canEditPlanContent}
                   onSave={(message) =>
                     updateAnnotationComment(
@@ -5753,6 +5772,7 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
                   currentUser={currentCommentAuthor}
                   pendingAuthor={pendingCommentAuthor}
                   isPending={commentWritePending}
+                  canComment={canCommentPlan}
                   onReply={replyToCommentThread}
                   canResolve={canResolveCommentThreads}
                   canDeleteThread={canDeleteCommentThread}
@@ -6219,7 +6239,7 @@ function PlanShareControl({
         peopleAccessLabel={t("plansPage.share.peopleAccess", { noun })}
         generalAccessLabel={t("plansPage.share.generalAccess", { noun })}
         roleCopy={{
-          viewer: {
+          commenter: {
             label: t("plansPage.share.commenterRoleLabel"),
             description: t("plansPage.share.commenterRoleDescription"),
           },
@@ -9164,6 +9184,7 @@ function AnnotationPopover({
   position,
   isPending,
   pendingAuthor,
+  canComment,
   canEditRootComment,
   onSave,
   onReply,
@@ -9179,6 +9200,7 @@ function AnnotationPopover({
   position: InlineCommentPosition;
   isPending: boolean;
   pendingAuthor: CommentAuthorPresentation;
+  canComment: boolean;
   canEditRootComment: boolean;
   onSave: (message: string) => void;
   onReply: (threadRootId: string, message: string) => Promise<void>;
@@ -9455,13 +9477,15 @@ function AnnotationPopover({
           })}
         </div>
       </div>
-      <div className="shrink-0 border-t border-border/70 p-3">
-        <ReplyComposer
-          author={pendingAuthor}
-          isPending={isPending}
-          onSubmit={(reply) => onReply(annotation.id, reply)}
-        />
-      </div>
+      {canComment && (
+        <div className="shrink-0 border-t border-border/70 p-3">
+          <ReplyComposer
+            author={pendingAuthor}
+            isPending={isPending}
+            onSubmit={(reply) => onReply(annotation.id, reply)}
+          />
+        </div>
+      )}
     </div>
   );
 }
@@ -9474,6 +9498,7 @@ function AnnotationsPanel({
   pendingAuthor,
   isPending,
   onReply,
+  canComment,
   canResolve,
   canDeleteThread,
   canDeleteComment,
@@ -9489,6 +9514,7 @@ function AnnotationsPanel({
   pendingAuthor: CommentAuthorPresentation;
   isPending: boolean;
   onReply: (threadRootId: string, message: string) => Promise<void>;
+  canComment: boolean;
   canResolve: boolean;
   canDeleteThread: (thread: CommentThread) => boolean;
   canDeleteComment: (comment: PlanCommentItem) => boolean;
@@ -9739,11 +9765,13 @@ function AnnotationsPanel({
                       />
                     );
                   })}
-                  <ReplyComposer
-                    author={pendingAuthor}
-                    isPending={isPending}
-                    onSubmit={(reply) => onReply(thread.id, reply)}
-                  />
+                  {canComment && (
+                    <ReplyComposer
+                      author={pendingAuthor}
+                      isPending={isPending}
+                      onSubmit={(reply) => onReply(thread.id, reply)}
+                    />
+                  )}
                 </article>
               );
             })

package/corpus/templates/plan/changelog/2026-08-12-viewers-are-read-only-and-commenters-can-comment.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-12
+---
+
+Shared plans now distinguish read-only viewers from commenters who can add review feedback without editing the plan.

package/corpus/templates/plan/server/plans.ts

@@ -724,8 +724,8 @@ export async function assertPlanEditor(planId: string) {
     if (!readable || !resource || resource.deletedAt) throw error;
     throw new ForbiddenError(
       resource.kind === "recap"
-        ? `Recap ${planId} is read-only for you (your role: ${readable.role}). Recaps are published review snapshots owned by whoever published them (often the PR recap workflow), and changing one requires editor access. Do not retry this call with the same arguments. Instead: (1) add review feedback with a comment-only update-visual-plan call or reply-to-plan-comment — commenting only needs viewer access; (2) publish an updated recap you own with create-visual-recap (pass its planId only when replacing a recap you own); or (3) ask the recap owner to share editor access.`
-        : `Plan ${planId} is read-only for you (your role: ${readable.role}); this operation requires editor access. Do not retry this call with the same arguments. Instead add feedback with a comment-only update-visual-plan call or reply-to-plan-comment — commenting only needs viewer access — or ask the plan owner to share editor access.`,
+        ? `Recap ${planId} is read-only for you (your role: ${readable.role}). Recaps are published review snapshots owned by whoever published them (often the PR recap workflow), and changing one requires editor access. Do not retry this call with the same arguments. Instead: (1) add review feedback with a comment-only update-visual-plan call or reply-to-plan-comment — commenting requires commenter access; (2) publish an updated recap you own with create-visual-recap (pass its planId only when replacing a recap you own); or (3) ask the recap owner to share editor access.`
+        : `Plan ${planId} is read-only for you (your role: ${readable.role}); this operation requires editor access. Do not retry this call with the same arguments. Instead add feedback with a comment-only update-visual-plan call or reply-to-plan-comment — commenting requires commenter access — or ask the plan owner to share editor access.`,
     );
   }
 }

package/corpus/templates/plan/shared/types.ts

@@ -200,7 +200,7 @@ export interface PlanReport {
 export interface PlanBundle {
   plan: Plan;
   access?: {
-    role: "owner" | "viewer" | "editor" | "admin";
+    role: "owner" | "viewer" | "commenter" | "editor" | "admin";
     ownerEmail?: string | null;
     orgId?: string | null;
     visibility?: "private" | "org" | "public" | null;