@aswless_854771076/ai_short_studio_cli 0.1.98 → 0.1.100

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/environment/model-and-provider.md

@@ -0,0 +1,275 @@
+# Choose and connect model services
+
+Read this when the work needs model access, the user brings an API key or deployment, or a selected
+service cannot fulfill the request. This page owns the connection decision and project extension
+path. [Profile](profile.md) owns configuration, credentials and routing; [local tools](local-tools.md)
+owns local preparation. Material Craft owns what the generated or transformed media should do.
+
+Go to [service choice](#choose-the-practical-capability-path-with-the-user),
+[BYOK connection](#connect-a-service-the-user-brings),
+[project implementation](#implement-the-missing-capability-in-the-project), or
+[diagnosis](#diagnose-the-actual-connection) as needed.
+
+## Start from the capability the work needs
+
+Identify the next useful result and the material already available. A face replacement or motion
+reference task needs an implementation supporting that operation and its actual references.
+It does not automatically require transcription, an image-generation step or a local render browser.
+An existing Output can satisfy a Run without another model call; [Build planning](../production/builds.md#plan-the-selected-run)
+identifies the remaining requests when a Run exists.
+
+Keep these responsibilities clear:
+
+| Part | What it decides |
+| --- | --- |
+| Model | Authored request meaning: exact model, text/media inputs, reference roles, parameters and result types |
+| Provider | How to fulfill that capability through an API or local process |
+| Endpoint | One configured Provider instance using a particular service, account or deployment |
+| Runtime Profile | Which Endpoints and Credential Stores are selected, and explicit bindings where needed |
+
+One Model can be served by different Providers when they implement its exact capability. One Provider
+can implement several Models. Installing a Model describes requests; it does not grant service access.
+Having a key grants only whatever the issuing service permits; it does not implement that service's API.
+
+## Choose the practical capability path with the user
+
+**For native video production, use StarRouter for generated video and StarRouter-routed Comfly for reference
+preprocessing.** MiniMax H3 also uses StarRouter. Existing direct Comfly and RunningHub production bindings must be replaced before new paid work. Every route remains limited by account access and rates.
+
+A user's existing service or deployment remains a normal choice. When a suitable maintained Provider
+package is available, use its published version and package instructions; otherwise a project Provider
+can connect the service through the same interfaces. The
+[model and deployment service page](https://github.com/hypit-ai/hypit/blob/main/docs/guide/service-partners.md)
+introduces partners and links their own documentation. A partnership alone does not establish that a
+particular capability, account or implementation is available. Carry an already suitable, chosen
+service forward.
+
+For original-reference depth preprocessing, the native default is Comfly `1194` subtitle removal →
+explicit original-timebase restoration → `1776` depth → restoration. Keep the original for all
+analysis/audio/subtitle times. Whole shots ≤15 seconds only; drift >5% and missing outputs block.
+The new Runtime uses a StarRouter API Key for Comfly through a Token CredentialRef, TempFile 1h,
+and durable public task receipts; see the Provider README. Confirm both `comfly/1194` and
+`comfly/1776` are enabled for the account before any paid submission. Existing direct Comfly Profiles may be read for history, but cannot submit new production tasks. Subtitle removal does not repair generated-shot errors.
+
+BYOK means using an account/key supplied by the user. A key connects only the service that issued it.
+OAuth and static keys are credential methods, not different
+model capabilities. A Profile can mix services by capability.
+
+| Route | What the user needs | What the Agent does |
+| --- | --- | --- |
+| An existing API service | Service identity, relevant API documentation/address and secure credential access | Reuse a compatible Provider or implement the needed API in the project |
+| A chosen deployment | Its serving API, access and compute/account choice | Connect that API; deploy only if deployment is actually part of the requested work |
+| Local inference | A suitable machine and an agreed preparation choice | Assess tools, resources and inference cost, then prepare the selected local Provider |
+
+### Reuse bundled StarRouter Providers
+
+Do not implement a project adapter when the selected Distribution already contains the matching
+Provider. Read its installed README for the current Profile fields and limits.
+
+| Service | Bundled Provider | Capabilities and important boundary |
+| --- | --- | --- |
+| Comfly through StarRouter | `@hypit/provider-comfly` with `transport=starrouter` | Original-reference subtitle removal (`comfly/1194`) and depth (`comfly/1776`); whole shot ≤15s/100MiB; TempFile 1h; explicit timebase restoration after each step |
+| StarRouter | `@hypit/provider-starrouter` | GPT Image 2, MiniMax H3, Seedance 2 and Seedance 2 Fast; GPT Image references upload directly, while H3/Seedance references use the starter's TempFile.org publisher; Seedance video/audio references require measured `duration-seconds` and matching `@视频N`/`@音频N` prompt labels |
+
+Model routing and prompt routing must agree. MiniMax H3 requests use an `h3:*` Surface and a prompt
+written with the bundled [H3 prompt-writing guide](../playbooks/craft/h3-prompt-writing.md); Seedance requests use a `seedance:*` Surface and its own
+reference-label conventions. Before a paid Build, inspect the effective Surface and binding after any
+node-level override. Stop on a mismatch instead of silently sending an H3 prompt to Seedance or a
+Seedance prompt to H3.
+
+StarRouter declares an `apiKey` credential slot. The StarRouter-routed Comfly adapter declares `token`;
+the StarRouter route points it to the same `starrouter.api-key` CredentialRef. Use
+`hypit auth login starrouter.comfly` if that Key is not stored yet; never put its value in the Profile.
+Select the service under `endpoints`, route the
+exact capability under `bindings` when more than one Endpoint offers it, then use `hypit auth login
+<endpoint>` with a writable Credential Store. The starter Runtime uses TempFile.org for temporary public references. Confirm the user accepts the public exposure and its expiry before a reference-led paid Run; do not drop references.
+
+For reference-led recreation, strongly recommend chaining `@hypit/depth-video@1#depth-video` into the existing H3 or
+Seedance `ReferenceVideo` Surface. Keep the character image and depth video as separate references,
+describe the latter as structure/motion/camera guidance in the Prompt, and call the result
+“depth-reference generation”, not native depth or ControlNet conditioning. StarRouter Seedance needs
+`person-reference="false" duration-seconds="…"` on the depth video, `duration-seconds="…"` on every
+audio reference, and matching `@图片N`/`@视频N`/`@音频N` labels in the Prompt; StarRouter H3 accepts the same depth Artifact as an ordinary video reference. The plan must
+show the depth request before the generated-shot request. Skipping it requires an explicit reason such
+as no useful temporal source, an incompatible target model, or a user-approved creative departure.
+
+StarRouter Seedance 2 does accept character images. Do not treat Seedance's `personReference` field
+as proof that an image is a prohibited real-person face. If StarRouter returns
+`InputImageSensitiveContentDetected.PrivacyInformation` or `fail_to_fetch_task`, the bundled Provider
+can optionally send HTTP(S) image references through BytePlus Ark asset review and retry once. Enable
+that path only by configuring `bytePlusAccessKeyId`, `bytePlusAccessKeySecret` and
+`seedanceAssetGroupId` together; `seedanceAssetProjectName` defaults to `hypit`. Without that optional
+configuration, preserve the original StarRouter error instead of retrying or dropping the image.
+
+Carry a suitable existing choice forward. Compare remaining setup work, capabilities, hardware,
+download/inference time and account costs. Ready local WhisperX can be useful immediately; first-time
+large-model preparation is a different choice. Cached weights reduce work but do not choose the route.
+A mixed setup, such as local alignment and hosted video generation, is ordinary.
+
+Explain consequential choices before a new account connection, substantial preparation or paid work.
+Use the user's settled account, budget and preparation scope without asking again for each command.
+Record decisions in the project's Brief or continuation notes. Revisit a route when new evidence changes
+its practicality; a failed service does not authorize switching the account or billing route.
+
+Hypit is the open-source tool. Hosted model services have their own accounts and billing.
+An installed Skill or executable supplies no model credits. A subscription alone does not establish
+access to the required model API. Explain cost for the actual remaining work and reuse;
+[Builds](../production/builds.md#work-within-the-agreed-paid-scope) owns spending estimates and submission.
+
+## Connect a service the user brings
+
+### Establish the service and intended operation
+
+Use already supplied information first. If something essential is missing, ask for the service name
+and API documentation or base address, plus the desired model/operation. Ask for secure authorization
+when the configured connection is ready; the user should not paste a key into the conversation.
+A key alone does not explain whether a service offers chat, images, reference-driven video,
+face replacement or motion control.
+
+The Agent owns API research, package implementation and Profile wiring. Explain what connection work
+remains in terms of the requested result. Each service issues its own credentials; a key from another
+vendor must not be entered for the selected Endpoint.
+
+### Decide what actually needs changing
+
+| User's situation | Appropriate action |
+| --- | --- |
+| Replace a credential for the same configured service/account | Update that Store entry; preserve its Endpoint reference |
+| Add another account on the same service | Add an Endpoint using the same Provider and a distinct credential key |
+| Use another deployment with the same complete protocol | Use the Provider's supported address configuration |
+| A published Provider implements the required Model for this service | Install the selected package version if needed; configure its Endpoint, credential slots and routing |
+| The Model exists but the API differs | Implement a project Provider for the existing capability |
+| The requested model/operation is not described | Add a project Model and a Provider implementing that capability |
+| An API works without a credential | Configure the Endpoint as its Provider declares; no auth command is needed |
+| Compute is available but no model service exists yet | Establish the selected serving deployment before connecting inference |
+
+Similar model labels and “OpenAI-compatible” branding do not establish matching upload, reference,
+job, result or authentication protocols. Changing `baseUrl` is valid only when the complete required
+protocol matches. Preserve authored requests: a narrower Provider reports its actual support rather
+than silently reducing duration, dropping references or changing resolution.
+
+### Configure, authorize and route the selected implementation
+
+Read that Provider's configuration and credential slots. Field names such as `apiKey` and `baseUrl`
+are Provider-owned, not universal Profile fields.
+
+For a concrete implementation example, the Distribution's `examples/provider-package` contains
+image and video Providers. After adapting and installing its video package for the real service,
+its Profile fragment has this shape:
+
+```json
+{
+  "credentials": {
+    "platform": { "use": "@hypit/credential-store-platform" }
+  },
+  "endpoints": {
+    "videos.personal": {
+      "use": "@example/provider-videos",
+      "config": {
+        "baseUrl": "https://videos.example",
+        "apiKey": { "store": "platform", "key": "videos.personal" }
+      }
+    }
+  },
+  "bindings": {
+    "@hypit/seedance@1#seedance-2-mini": "videos.personal"
+  }
+}
+```
+
+The example API and address are illustrative, not a working vendor connection. Replace its transport
+and address with the selected service's actual protocol, and use the installed package name.
+The capability above is the existing Seedance Mini capability that this example implements;
+copy the real Model's complete capability reference for a different request.
+
+Then use the declared acquisition method:
+
+```bash
+hypit auth login videos.personal
+hypit plan ./production.svrun
+hypit pricing ./production.svrun
+```
+
+The example Provider has a writable key slot and no browser flow, so login securely prompts for the
+key. An Endpoint declaring OAuth instead opens its flow; `--from <private-file>` selects file import.
+A read-only environment Store is configured in the execution environment rather than through login.
+
+The binding directs this capability to the selected Endpoint when multiple implementations exist.
+It does not send another service's key to this Endpoint. Other capabilities can keep their existing route.
+`plan` reports support and cheap readiness for known inputs; `pricing` reads service-owned rate
+information. Submit the real request within the agreed scope; these checks do not prove that a paid
+generation has already succeeded.
+
+## Implement the missing capability in the project
+
+Inspect the Model vocabulary, its README and the service's API. Reuse a compatible implementation
+when present; otherwise create the needed `packages/provider-…` in this production. A project
+extension uses public interfaces and does not require an official framework release.
+
+Follow one actual request:
+
+1. Identify the exact capability, input roles and result type. A new Model owns new author semantics;
+   another API for an existing Model belongs in its Provider.
+2. Map text, scalar parameters and every supplied media role/field to the real API. Declare actual
+   service limits through `supports`, including what is knowable before generated inputs exist.
+   Account-visible catalogue evidence can refine availability when the service provides it.
+3. Implement immediate execution or the real `start`, `poll` and `collect` lifecycle. Checkpoint
+   an acknowledged task receipt promptly; Runtime owns continued scheduling. Report progress and
+   preserve public failure evidence without exposing credentials or signed URLs.
+4. Admit returned media through `context.resources` and return the declared result type. Configure
+   capacity for the actual resource and expose the service's price source and applicable units.
+5. Compile and install the package with the project's package manager, select its `use` and bindings,
+   and exercise the requested path within the user's existing authorization.
+
+Locate the complete `examples/provider-package/README.md` through `hypit paths`. Use its
+`provider-images` or `provider-videos` package according to the request shape. The video example
+covers image/video/audio references, first/last frames, required visual-reference person classification and separate
+result collection. Its mappings, limits and transport are examples to adapt, not a new shared API.
+Implement only the service capabilities this work needs.
+
+The Provider's `supports` response describes its actual range without narrowing the shared Model or
+silently changing an author's request.
+
+## Use the public SDK
+
+| Public import | Accurate interface owner |
+| --- | --- |
+| `@hypit/hypit/model-kit` | Model ports and Producer/Need construction |
+| `@hypit/hypit/generation` | Generated-media values and request/mapping helpers |
+| `@hypit/hypit/endpoint-kit` | Execution, resources, credentials, support, receipts and capacity |
+| `@hypit/hypit/runtime-kit` | Profile activation, diagnostics and Managed Programs |
+| `@hypit/hypit/author-kit` | Author Module, Surface and Fragment declarations |
+
+These packages' READMEs ship with the Distribution and own precise APIs. Use the selected
+`@hypit/hypit` release as the extension's development dependency; ship compiled JavaScript and normal
+runtime dependencies. The copied repository example's `workspace:*` development dependencies need
+the appropriate installed release, as its README explains.
+[Component sharing](../production/component-sharing.md) owns later owner-managed distribution.
+
+## Use your own model deployment
+
+If the user already has a serving API, connect it by the same Provider path. If they have compute
+but no service, use that platform's current deployment guidance and the model's serving instructions.
+Explain persistence, hardware and cost for the actual deployment. Management credentials and inference
+credentials may serve different operations. Deployment lifetime remains separate from generation jobs.
+
+Local inference uses the same boundary. A Provider can invoke a local process; a Managed Program
+declares preparation and an optional persistent helper when needed. [Local tools](local-tools.md)
+explains using that declaration. The selected implementation owns its service protocol.
+
+## Diagnose the actual connection
+
+A missing adapter, rejected credential, unavailable model, unsupported input and exhausted quota
+call for different actions. Keep the Endpoint, model/operation and returned public status/code/reason
+with the evidence. An isolated `401` or `model_not_found` does not prove that payment or another
+login will fix the request. Read account-visible service information when availability is in question.
+
+Use current API documentation and the installed implementation to pursue a proportionate fix.
+A relevant [release update](distribution.md#check-and-update-the-relevant-installation), configuration
+change or project adapter repair can move the work forward. Report the actual change and what was
+verified; a repaired installation's success is distinct from the original release's behavior.
+Framework maintenance follows its repository instructions; this Skill owns production and public
+package extensions.
+
+Keep independent work moving when a capability is unavailable, and explain the specific deliverable
+still waiting for it. Preserve the user's chosen service and intended result while resolving that gap.

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/environment/profile.md

@@ -0,0 +1,286 @@
+# Configure the Runtime Profile
+
+Read this when selecting a project's execution environment, wiring Endpoints and credentials,
+setting shared capacity, or deciding when a configuration change takes effect.
+[Models and Providers](model-and-provider.md) owns service choice and BYOK;
+[local tools](local-tools.md) owns preparation and process management.
+
+Go to [Profile selection](#create-a-profile-when-the-project-needs-one),
+[configuration structure](#read-and-edit-the-actual-configuration),
+[routing](#connect-model-capability-need-and-endpoint),
+[credentials](#put-secrets-behind-credential-references),
+[capacity](#set-capacity-at-the-resource-it-describes), or
+[change effects](#know-when-a-change-takes-effect) as needed.
+
+## Create a Profile when the project needs one
+
+From the project directory:
+
+```bash
+hypit runtime init
+hypit paths
+```
+
+`runtime init` writes and selects an editable starter `hypit.runtime.json`. It preserves an existing
+Profile and performs no installation or login. Its hosted generation/alignment, local media and local
+rendering entries are initial routing choices, not a requirement to prepare every service for every
+video. Keep the entries and bindings appropriate to the work and the user's chosen setup.
+
+Use `hypit runtime use <profile>` to record an existing Profile for this project.
+`--runtime <profile>` selects one for a single invocation. Commands read the project's
+`.hypit/runtime` selection file; they do not guess from a familiar filename or another project's
+selection. From elsewhere, `hypit paths --workspace /path/to/project` inspects that project. The same
+project option applies to environment commands and Build status/control. See the
+[project boundary](../creation/project-files.md#establish-the-project-boundary).
+
+Keep these locations distinct:
+
+| Location | Responsibility |
+| --- | --- |
+| Project directory | Sources, Runs, assets and component dependencies |
+| `.hypit/runtime` | File naming the selected Profile |
+| Profile file | Editable execution choices; may be shared intentionally |
+| Profile `dataRoot` | Execution data, Worker state and working files; relative to the Profile's directory |
+| Host state / Program Home | Machine-level prepared packages and helpers, reported by `hypit paths` |
+| Project Result repository | Finished Results and Outputs; configured separately in `hypit.results.json` |
+
+The selection file and execution directory must be different paths. CLI, Studio and creation
+commands address the same project context; there is no second CLI environment to initialize.
+Installed code, selected configuration and existing execution data remain separate.
+
+## Read and edit the actual configuration
+
+A complete minimal Profile for credential-free local media work is:
+
+```json
+{
+  "format": "hypit.runtime-local@1",
+  "dataRoot": ".hypit/execution",
+  "credentials": {},
+  "endpoints": {
+    "media.local": {
+      "use": "@hypit/provider-media-local"
+    }
+  },
+  "bindings": {}
+}
+```
+
+This selects media processing only. It needs compatible FFmpeg and FFprobe supplied by the host;
+it does not install them, select an image model, or render HyperFrames pictures. Use it when those
+are the actual requirements, not as a replacement for a production's existing Profile.
+
+| Field | How to choose it |
+| --- | --- |
+| `credentials` | Named Credential Store adapters; empty when no selected Endpoint needs a secret |
+| `endpoints` | Named Provider instances. `use` selects the package; its README defines `config` |
+| `bindings` | Complete capability keys mapped to Endpoint instance names |
+| Endpoint `pool` | Optional identity of a real shared account, deployment or compute quota |
+| `dataRoot` | Where this Runtime keeps execution state; changing it selects different state |
+| Optional `worker.executionMemoryMb` | Memory budget for Build execution processes; startup policy owned by the Runtime package |
+
+Merge documentation fragments into the corresponding existing objects. Retain other services,
+credential references and bindings the project uses. A fragment without `format` and `dataRoot`
+is not a complete Profile. Package installation makes an adapter available; declaring it here
+selects an instance. Configuration keys belong to that package, so a `baseUrl` or `apiKey` field
+from one Provider is not a universal schema for all Providers.
+
+## Connect Model, capability, Need and Endpoint
+
+The [Model and Provider roles](model-and-provider.md#start-from-the-capability-the-work-needs)
+keep authoring separate from deployment. One authored request produces a concrete external **Need**
+only if its output remains demanded by the Run. Existing Result Candidates can satisfy that output
+without another generation request.
+
+A **capability** identifies the required operation. The Profile routes it to an **Endpoint**, a
+configured Provider instance. A **binding** is that explicit routing choice. For example, after
+declaring and configuring `whisperx.local`, merge:
+
+```json
+{
+  "bindings": {
+    "@hypit/whisperx@1#whisperx-alignment": "whisperx.local"
+  }
+}
+```
+
+Use the complete capability key from the Model/Provider vocabulary, not a vendor model label.
+The named Endpoint must actually offer it and support the concrete request. One eligible Endpoint
+needs no binding; several unbound choices are an error, not a fallback order. This lets the same
+Source use local alignment in one deployment and hosted alignment in another.
+
+Explicit bindings let capability-scoped commands load the named Endpoints directly. Without a
+binding, discovering eligible implementations can require loading the declared Endpoint packages;
+an uninstalled declared package can therefore block discovery. Correct the declaration or select
+the intended binding. An unused account need not be logged in merely to resolve the work.
+
+The complete local alignment example is in
+[local WhisperX](local-tools.md#select-local-whisperx-explicitly). Hosted and BYOK examples are in
+[service connections](model-and-provider.md). Result storage and project-package resolution are
+separate from this routing.
+
+## Put secrets behind credential references
+
+A Profile names a Store and a key. The value stays in that Store.
+
+| Store package | Storage and use |
+| --- | --- |
+| `@hypit/credential-store-platform` | Starter policy: macOS Keychain, Windows Credential Locker, or an owner-private unencrypted file on Linux |
+| `@hypit/credential-store-os` | Explicit OS locker selection on supported platforms |
+| `@hypit/credential-store-file` | Explicit unencrypted private file storage outside the project |
+| `@hypit/credential-store-env` | Reads one named environment variable; read-only |
+
+The platform policy selects by operating system; it is not a sequence of stores to try.
+A read failure never migrates a secret or falls back to another Store. Preserve an existing choice.
+The platform/file Store's default file directory is under the Host state root shown by `hypit paths`;
+its optional `config.path` chooses a private directory. Read that Store's installed README for path
+and platform rules, including filesystem permissions.
+
+To select a Store explicitly, name it under `credentials` and use that name in the Endpoint's
+credential reference. A credential-free Endpoint needs no auth command; prepare its tools directly.
+
+For example, these are the Store declaration and credential reference used by a StarRouter Endpoint:
+
+```json
+{
+  "credentials": {
+    "platform": { "use": "@hypit/credential-store-platform" }
+  },
+  "endpoints": {
+    "starrouter.video": {
+      "use": "@hypit/provider-starrouter",
+      "config": {
+        "apiKey": { "store": "platform", "key": "starrouter.api-key" }
+      }
+    }
+  }
+}
+```
+
+After the user has chosen that account connection:
+
+```bash
+hypit auth login starrouter.video
+```
+
+A Provider declaring browser acquisition uses that flow immediately. Otherwise, a writable Store
+uses secure terminal input. `--from /private/path/key.txt` explicitly imports a secret file instead
+of opening OAuth. Wait for CLI success: a successful browser callback alone does not establish
+that the Store write succeeded. Login/logout can replace/remove a damaged value without reading it;
+status and execution still report read errors.
+
+For an intentionally environment-backed deployment, merge this alternative Store and change the
+selected Endpoint's credential reference accordingly:
+
+```json
+{
+  "credentials": {
+    "env": { "use": "@hypit/credential-store-env" }
+  },
+  "endpoints": {
+    "starrouter.video": {
+      "use": "@hypit/provider-starrouter",
+      "config": {
+        "apiKey": { "store": "env", "key": "STARROUTER_API_KEY" }
+      }
+    }
+  }
+}
+```
+
+Here `STARROUTER_API_KEY` is the explicitly selected variable name. Supply it securely to both
+the CLI commands that need it and the Worker process at startup. `auth login` cannot write an
+environment Store. Changing a terminal's environment does not change an already running Worker.
+Other services use their own Endpoint, credential slot and variable, not this StarRouter example.
+
+Use distinct Endpoint names and credential keys for separate accounts. Binding selects which one
+serves the requested capability; entering another service's key does not change the Provider.
+Local credential-free Endpoints need no login. `auth status <endpoint>` reports declared slots
+without revealing values; configured does not mean accepted, funded, reachable, or authorized for
+every model. Keep secrets out of Sources, Runs, Profile JSON, command arguments, commits and chat.
+
+## Set capacity at the resource it describes
+
+The Runtime Worker advances Builds. HyperFrames `workers` counts Chrome processes inside one
+render Need. These are different controls; there is no extra Build-wide model concurrency setting.
+
+| Control | Responsibility |
+| --- | --- |
+| Provider request capacity, commonly `config.defaultConcurrency` | Simultaneous Needs across Builds using the resource |
+| Provider-specific model/action limits | Model quota or submit/poll/collect concurrency and rate; use that Provider's accepted fields |
+| Endpoint `pool` | Shared resource identity for instances consuming the same real quota |
+| HyperFrames `workers`, `maxWorkers` | Per-render Chrome count or automatic ceiling |
+| HyperFrames `browserCapacity` | Shared Chrome budget alongside the whole-request budget |
+
+For example, merge this Endpoint entry for an intentionally chosen render budget:
+
+```json
+{
+  "endpoints": {
+    "hyperframes.local": {
+      "use": "@hypit/provider-hyperframes-local",
+      "pool": "local-render",
+      "config": {
+        "defaultConcurrency": 2,
+        "workers": 4,
+        "browserCapacity": 6
+      }
+    }
+  }
+}
+```
+
+Only one four-browser request fits the six-browser budget at once, even though the request limit is
+two. These numbers illustrate the relationship; choose them for the actual machine. HyperFrames
+reserves both budgets until the whole render finishes, including preparation and encoding.
+It does not release capacity each time one browser closes.
+
+Instances sharing a pool must agree on its limits. Separate accounts do not share one merely because
+they offer the same model. Capacity coordination covers Builds sharing a Runtime Execution Store;
+it is not a cross-machine account quota service. Accepted asynchronous Operations retain their task
+claim while pending. Short submit/poll/collect calls have separate action budgets when declared.
+Ending a Build attempt releases local claims while retaining receipts and last known remote state;
+it does not imply a remote task has been cancelled.
+
+Use `hypit activity` when actual claims matter. The installed Runtime and Provider READMEs own the
+exact settings. Studio's permitted transient work has session-local concurrency.
+
+## Ask each command for the fact it owns
+
+| Question | Command and boundary |
+| --- | --- |
+| Which project, Profile and storage locations apply? | `hypit paths` |
+| Is a named credential present? | `hypit auth status <endpoint>`; no account-access guarantee |
+| What will this Run demand? | `hypit plan <run>`; concrete requests, support checks and cheap readiness of their selected Endpoints |
+| Can the selected services be reached and used? | `hypit doctor --endpoint <instance>`; bounded active diagnosis, no generation submission |
+| Is the Worker running and work active? | `hypit runtime status` |
+| Which local helpers answer, and where are their logs? | `hypit programs status --endpoint <instance> --verbose` |
+
+Choose the observation needed now; this is not a mandatory sequence before every operation.
+Without a selected Profile, `doctor` checks project Results only. With one, it may contact remote
+services for bounded diagnostics. `plan` does not actively probe remote services or install missing
+resources. Neither command prepares every language model just because a local service is healthy.
+
+Prepare the selected resources and start needed helpers through
+[local Program commands](local-tools.md#let-the-selected-endpoint-own-its-program).
+A missing capability can leave independent Script, reference or component work possible; explain
+which requested outcome still depends on it. [Review](../production/review.md#show-what-the-current-work-establishes)
+distinguishes useful intermediate evidence from the intended deliverable.
+
+## Know when a change takes effect
+
+| Change | What to do |
+| --- | --- |
+| Source, Run or project component implementation | Create a new Build for the changed work |
+| Endpoint config or binding | New Builds read current choices; an existing Build retains its selected configuration |
+| Writable Store credential value | Subsequent credential resolution uses that Store; changing a secret is not a blanket Worker restart instruction |
+| Distribution installation, Worker startup policy or its inherited environment | Restart the Worker explicitly when active work permits |
+| A running local service's model, device, compute, batch size or cache location | Prepare its selected resources, then restart that helper when idle |
+| Additional WhisperX alignment language in the same cache | Run scoped `programs prepare`; the service can stay running |
+| Browser download mirror | Used for the next required preparation; a healthy cached browser remains usable |
+| Profile used by an existing Studio session | Restart the session if it needs to load the edited selection |
+
+A new Build's execution context is not a snapshot of every external file or service.
+Read [Build execution scope](../production/builds.md#build-with-the-current-project-implementation)
+before restarting a coordinator or changing dependencies during active work.
+Do not restart everything after every edit, or expect a completed Build to rerun itself.