axhub-commentary

Axhub Commentary workflow

First determine the workstream, then read the corresponding sub-document and perform the necessary checks according to the task. Do not require the target project to install the editor runtime; the editor is provided by the Axhub Chrome extension or the host preview environment.

0. Detect ACP UI as needed

For annotation reading and processing, first read the local comments.jsondirectly, without detecting the ACP UI; only when local annotations cannot be located, read, or pass format validation, detect the ACP UI, and after the service is ready, generate a temporary annotatable address and give it to the user. Detection is also required when the user directly requests generating an annotatable address, using AI conversation/execution, or host resource tools.

• Access http://localhost:32124/api/health, and it is considered ready only when the response satisfies both status: "ok" and service: "acp-ui" ; port occupation, the page being openable, or the existence of related processes cannot replace this detection.
• Only when detection fails, read references/acp-native-bootstrap.md, start it according to the original non-sandbox rules, and confirm health again. Native Host is an optional capability for later; register it only when the user explicitly confirms or actively requests installation.

Commentary's AI conversation, AI annotation execution, provider session, host resource tools, and local annotation source read/write depend on the ACP UI; when health is not confirmed, these capabilities must not be claimed to be ready. Reading and writing back local annotation records and tweaks, attribute adjustments, and in-page scheme switching do not depend on the ACP UI.

Workstreams

First determine which workstream the task belongs to, and read only the corresponding reference file.

1. Annotation reading and processing (primary)

When the task involves page annotations, revision comments, annotation images, annotation status, or explicitly deleting annotation nodes, read references/comment-processing.md。

2. Annotatable address and environment preparation (primary)

When the task is to generate an annotatable address or confirm page positioning, read references/environment-context.md. Here, prioritize the temporary link solution that does not modify project files; only when the user explicitly requests a stable entry point, proceed to fixed integration.

Figma is the exception: the final link only appends the absolute projectPathto the original Figma URL, without adding try-plugin-*. The extension must first complete binding according to the stable file identity, and then start Drafito itself.

3. Annotation environment preparation (primary)

When the user needs Annotation capabilities, handle according to the target:

1. Need to enable Annotation Runtime: read axhub-annotation-standalone to complete page integration.
2. Need to let the extension modify annotation content: ensure the page uses an editable annotation source. Place external JSON in the same directory as the current filePath and name it annotation-source.json; for a single HTML page, embed the annotation source in the current HTML and make annotationSourcePath point to that file. Provide projectPath、filePath and the necessary annotationSourcePaththrough the page context, generate and open an annotatable address, and give it to the user. Only when the annotation source does not conform to the above two conventions, read references/environment-context.md to handle custom paths.

4. AI conversation and annotation execution (primary)

When the task involves AI sidebar conversation, waking up the page AI, handing annotations to AI for execution, configuring providers, or troubleshooting provider software installation, terminal availability, and login authorization, read references/ai-capabilities.md. For the supported scope, see that document; the actual visible items and default items are subject to the current ACP UI configuration.

5. Page-side integration (low frequency)

Only when the user explicitly requests changes to page integration capabilities, read the corresponding sub-document according to the goal:

• Adjusting panel properties, page-level property aggregation → read references/property-editing.md
• Multi-option design comparison, in-page option switching → read references/design-bid.md

Property adjustment and multi-option comparison are both low-frequency, on-demand capabilities. This is the work line for modifying page code; temporarily annotatable links and editing annotations on existing Runtime content do not belong to page-side integration, and you should not modify the business page implementation for them.

When annotation requires adding integration capabilities, you may cross work lines: first read the annotation handling process to determine the task, then supplement by reading one page-side integration reference according to the specific goal.

Implementation order

1. First determine whether the task belongs to main process 1, 2, 3, or 4; enter low-frequency process 5 only when the user explicitly requests it.
2. Read only the sub-document for the matched process; for annotation handling, read the local record first, and only after failure detect ACP UI and generate a temporary address; for other processes, detect according to the usage conditions above.
3. Only when detection is needed and health fails, read references/acp-native-bootstrap.md, do not load startup details in advance.
4. After annotation handling succeeds, first write completed and keep the node, then ask the user whether to clear it; after the user confirms, write only the deletion marker, and the actual cleanup is uniformly executed by the extension. Temporary addresses do not modify project files by default; after page-side integration is complete, verify the write-back capability.

Delivery requirements

The final reply includes the necessary information according to the matched sub-process:

• ACP UI: whether health has been confirmed; if the user needs to start it manually, provide the exact command and the current blocking status
• Annotation handling: which interface modifications were completed, whether there are still unhandled or abnormal annotations, which verifications were done; after writing completed , ask the user whether to clear
• Annotation environment: annotatable address, the annotation source form used and the actual path; if incomplete, explain whether Runtime integration or page context is missing
• AI capabilities: the selected provider, whether the CLI and login are ready, whether the provider session is available; do not expose tokens or other credentials
• Page integration: which files were modified, which properties or option fields were exposed, which verifications were done
• Keep the reply user-facing; do not treat internal annotation status, synchronization details, or command logs as the main content

Reference

• references/comment-processing.md
• references/ai-capabilities.md
• references/property-editing.md
• references/design-bid.md
• references/environment-context.md
• references/acp-native-bootstrap.md