@comty.io/core 0.1.6 → 0.1.8

package/README.md

@@ -37,12 +37,15 @@ import { initComty } from '@comty.io/core';
 
 await initComty({
   projectKey: 'YOUR_PROJECT_KEY',
-  apiUrl: 'https://YOUR_COMTY_API',
 });
 ```
 
 Call once from your application entry. Server rendering is safe: it does nothing until called in a browser. Repeated calls with the same options reuse the document's instance. Reload the page to change its project or API URL. Register the site's domain in Comty to use shared comments.
 
+The project key is the only required option for hosted Comty. The SDK connects to `https://api.comty.io` by default, including when your application runs on localhost. You do not need an API URL environment variable or your own Comty server. Set `apiUrl` only when using a different Comty API, such as `http://localhost:4000` for developing Comty itself or the URL of a self-hosted installation.
+
+The browser entry also works in production. If Comty should only appear in development or preview, conditionally call `initComty` in your application. To include production, do not guard initialization with a development-only flag. The Vite companion below is a separate development-only integration.
+
 ## Color tokens
 
 Element inspection shows a copyable CSS custom-property name above foreground/background colors when the winning declaration can be identified. It handles ordinary selectors, `:where()`, inline styles, inheritance, `!important`, active media/supports rules and named top-level cascade layers. Semantic aliases retain their declared name. No extra line is rendered for literal colors or uncertain provenance (including inaccessible stylesheets, shadow/scoped or nested cascades, and unsupported functional selectors).
@@ -81,7 +84,7 @@ export default defineConfig({
 });
 ```
 
-Keep your existing plugins. Run your normal dev command and open `http://localhost:<vite-port>`. The plugin injects the SDK and starts the companion automatically. It is disabled for production builds. Choose the installed coding agent with `agent: 'codex' | 'claude' | 'cursor' | 'gemini' | 'grok'`. The optional `model` setting accepts a model ID from the selected agent; omit it to use that agent's default. A project key is optional in local Agent mode; set `projectKey` and `apiUrl` in the plugin options if you also want shared Comty comments.
+Keep your existing plugins. Run your normal dev command and open `http://localhost:<vite-port>`. The plugin injects the SDK and starts the companion automatically. It is disabled for production builds. Choose the installed coding agent with `agent: 'codex' | 'claude' | 'cursor' | 'gemini' | 'grok'`. The optional `model` setting accepts a model ID from the selected agent; omit it to use that agent's default. A project key is optional in local Agent mode; set `projectKey` in the plugin options if you also want shared Comty comments. Set `apiUrl` only for a local or self-hosted Comty API.
 
 ## Other development servers
 
@@ -97,11 +100,11 @@ Optional flags: `--port`, `--model`, `--project-key`, `--api-url`. Without a com
 
 ### Choose your coding agent
 
-Install and sign in to the coding agent CLI you want to use, then set `--agent` (or the Vite plugin's `agent` option). This selects a **coding agent**, not just a model API: the CLI reads the project, edits files and runs checks. Comty does not install the agent or provide its credentials.
+Use the coding agent CLI already installed and signed in on your computer, then set `--agent` (or the Vite plugin's `agent` option). It must be available on the development server's `PATH`; no agent package is needed in your project. This selects a **coding agent**, not just a model API: the CLI reads the project, edits files and runs checks. Comty does not install the agent or provide its credentials. If the CLI is missing, install it once using that agent's instructions. If its version does not support your chosen model, update that existing CLI.
 
 To choose a model, add `model: 'your-agent-model-id'` to the Vite plugin or `--model your-agent-model-id` to `comty dev`. Model IDs belong to the selected agent and must be available on your account. Leave this option out to use its CLI default.
 
-| Agent | `agent` value | CLI to install and sign in to |
+| Agent | `agent` value | Existing CLI command |
 | --- | --- | --- |
 | Codex | `codex` | `codex` |
 | Claude Code | `claude` | `claude` |
@@ -115,10 +118,10 @@ Gemini CLI runs through its [ACP mode](https://github.com/google-gemini/gemini-c
 
 ## Using the agent
 
-Codex and Claude use the project's local CLI when present, otherwise `codex` or `claude` on PATH. Cursor uses `agent`, Gemini uses `gemini`, and Grok Build uses `grok` on PATH. Tool permission requests are relayed to the Comty sidebar; Claude uses a local MCP tool for this. Comty does not provision an AI subscription or credentials.
+Comty resolves each agent through the development server's PATH: `codex`, `claude`, `agent` (Cursor), `gemini`, or `grok`. It reuses that CLI's configuration and login. Tool permission requests are relayed to the Comty sidebar; Claude uses a local MCP tool for this. Comty does not provision an AI subscription or credentials.
 
-1. Open the toolbar with Shift S or Shift I.
-2. Select the `</>` Agent tool and click an element.
+1. Press **Shift A** to open Agent mode directly (localhost only), or select the `</>` Agent tool from the toolbar.
+2. Click an element.
 3. Ask a question or describe a change. **Apply globally** is off by default, so the request targets this element. Turn it on to request a change to every instance of the same component variant. The agent must identify that component and variant in source before applying the broader change. No Comty account is needed for this local flow.
 4. Work in progress is indicated on the element, without a progress toast. Click the Agent tool again to read the latest answer or change summary. Requested tool permissions and errors still appear when they need attention.
 5. In an existing shared comment thread, reply with `@Agent` to start a local agent task. Your question and the agent's response remain in the shared thread. This requires a project editor account, a project key, and the local companion running in your browser. Without `@Agent`, replies remain ordinary human comments.
@@ -130,3 +133,11 @@ Comty starts a separate agent session. It does not send instructions into an alr
 Direct Agent requests are never sent to the Comty API or its database. Their prompt and page context are sent to the selected AI provider by its coding agent. In a shared thread, the `@Agent` message and final answer are stored as comment replies; the thread transcript and page context are sent to the selected coding agent. Standard shared comments retain their existing Comty authentication and storage.
 
 Add `.comty/` to your application's `.gitignore`. Keep the companion on loopback; LAN binding, tunnels and production hosting are unsupported. Requests require the random token of the running development session and its exact origin.
+
+## Inspector annotations and area captures
+
+In Inspect (**Shift I**), choose **Annotate** (**D**) to draw with a pencil, rectangle, ellipse or arrow. Choose a stroke from the visual width buttons and a color from the swatches or the custom color picker. **⌘/Ctrl Z** undoes the last annotation; the trash button clears all drawings. **Escape** cancels an unfinished stroke, then exits the tool. Drawings follow document scrolling, remain when changing tools, and reset on navigation or reload.
+
+Choose **Capture area** (**S** while inspecting), then drag a rectangle in either direction to download a PNG. The image includes visible annotations, ruler strips, ruler guides, layout guides and distance measurements, without the toolbar or selection controls. **Escape** cancels. Captures stay local and use the existing DOM snapshot engine; inaccessible embedded pages and protected media may not appear exactly as rendered by the browser.
+
+The local Agent refreshes on entry and when returning to the tab. It polls only while tasks are pending or running; those progress checks do not reload shared comments. Inspector tools make no polling requests while idle.