vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/__init__.py

@@ -0,0 +1,11 @@
+"""Universal Vidbyte CLI.
+
+Import-side-effect free on purpose: importing this package must not build commands, read
+credentials, or touch the network.
+"""
+
+from .lib.runtime.version import current_version
+
+__version__ = current_version()
+
+__all__ = ["__version__"]

vidbyte_cli/__main__.py

@@ -0,0 +1,6 @@
+"""Enables `python -m vidbyte_cli`. The only job here is turning a status into SystemExit."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

vidbyte_cli/cli.py

@@ -0,0 +1,18 @@
+"""The callable behind the `vidbyte-cli` console script.
+
+Deliberately thin: lifecycle and the error trap live in `lib/runtime/application.py`, and
+process termination lives in `__main__.py` and the generated console wrapper. `main()`
+returns a status rather than calling `sys.exit`, so an embedding caller can run the CLI
+without having its own process killed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from .lib.runtime.application import CliApplication
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    # Returns the status; only an executable wrapper may terminate the process.
+    return CliApplication().run(argv)

vidbyte_cli/commands/__init__.py

@@ -0,0 +1,86 @@
+"""Single registration point for the CLI's whole command surface.
+
+Every command is static and known at release time — there is no manifest-driven or otherwise
+dynamic subtree, so this file is the complete list of what `--help` can show. A command
+belongs here only when a shipped backend route can answer it.
+
+Registration must stay side-effect free: every help and version invocation executes it.
+"""
+
+from __future__ import annotations
+
+import click
+
+from .agents import AgentsGroup
+from .auth.login import LoginCommand
+from .auth.logout import LogoutCommand
+from .auth.whoami import WhoamiCommand
+from .billing import BillingCommandGroup
+from .config.get import ConfigGetCommand
+from .config.set import ConfigSetCommand
+from .provider.login import ProviderLoginCommand
+from .provider.logout import ProviderLogoutCommand
+from .provider.whoami import ProviderWhoamiCommand
+from .research.add import ResearchAddCommand
+from .research.resume import ResearchResumeCommand
+from .research.start import ResearchStartCommand
+from .research.status import ResearchStatusCommand
+from .research.thread import ResearchThreadCommand
+from .research.threads import ResearchThreadsCommand
+from .research.watch import ResearchWatchCommand
+from .runtime import (
+    AdversarialTeamCommand,
+    PersistenceCommand,
+    RuntimeDoctorCommand,
+    RuntimeListCommand,
+    SameHostEnsembleCommand,
+    StagesCommand,
+    TaskBoardCommand,
+)
+from .setup.doctor import DoctorCommand
+from .setup.star import StarCommand
+
+
+def register_all_commands(program: click.Group) -> None:
+    # Attaches every command group to the root program; the surface is entirely static.
+    LoginCommand().register(program)
+    LogoutCommand().register(program)
+    WhoamiCommand().register(program)
+    DoctorCommand().register(program)
+    # Local and explicit-only: it has no backend route; see docs/design/pypi-release-and-star.md.
+    StarCommand().register(program)
+    AgentsGroup().register(program)
+
+    BillingCommandGroup().register(program)
+
+    # The whole public API-key research surface: start, add, resume, read, watch, list.
+    research = click.Group(name="research", help="Run and inspect Vidbyte research threads")
+    ResearchStartCommand().register(research)
+    ResearchAddCommand().register(research)
+    ResearchResumeCommand().register(research)
+    ResearchStatusCommand().register(research)
+    ResearchWatchCommand().register(research)
+    ResearchThreadsCommand().register(research)
+    ResearchThreadCommand().register(research)
+    program.add_command(research)
+
+    runtime = click.Group(name="runtime", help="Run Vidbyte primitives on this machine")
+    RuntimeListCommand().register(runtime)
+    RuntimeDoctorCommand().register(runtime)
+    AdversarialTeamCommand().register(runtime)
+    PersistenceCommand().register(runtime)
+    SameHostEnsembleCommand().register(runtime)
+    TaskBoardCommand().register(runtime)
+    StagesCommand().register(runtime)
+    program.add_command(runtime)
+
+    config = click.Group(name="config", help="Manage CLI configuration")
+    ConfigGetCommand().register(config)
+    ConfigSetCommand().register(config)
+    program.add_command(config)
+
+    provider = click.Group(name="provider", help="Manage BYOK provider API keys")
+    ProviderLoginCommand().register(provider)
+    ProviderLogoutCommand().register(provider)
+    ProviderWhoamiCommand().register(provider)
+    program.add_command(provider)

vidbyte_cli/commands/agent_options.py

@@ -0,0 +1,53 @@
+"""Reusable Click options for future commands that invoke local agents.
+
+The option declaration stays separate from attachment resolution so command parsing remains
+cheap and the same validated bundle can be reused by every future agent service.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from pathlib import Path
+
+import click
+
+from ..lib.io.attachments import AttachmentResolver
+from ..types.attachments import AttachmentBundle
+
+CommandCallback = Callable[..., None]
+OptionDecorator = Callable[[CommandCallback], CommandCallback]
+
+_ATTACH_HELP = (
+    "Attach one explicit local file as context for the future agent invocation. "
+    "Repeat this option once per file; occurrence order is preserved in the resolved bundle. "
+    "Text files are captured as UTF-8 snapshots and supported images remain native "
+    "local-image inputs. "
+    "Missing, duplicate, empty, unsupported, or oversized files fail before credentials, "
+    "payment, or model execution."
+)
+
+
+class AgentAttachmentOptions:
+    """Declares and resolves the shared repeatable `--attach PATH` option."""
+
+    def apply(self, callback: CommandCallback) -> CommandCallback:
+        # Keeps Click syntax in commands while delegating all validation to the shared resolver.
+        return click.option(
+            "--attach",
+            "attachments",
+            multiple=True,
+            type=click.Path(path_type=Path),
+            help=_ATTACH_HELP,
+        )(callback)
+
+    def resolve(self, values: Mapping[str, object]) -> AttachmentBundle:
+        # Extracts Click's tuple value and resolves it exactly once for the invocation.
+        raw = values.get("attachments", ())
+        if not isinstance(raw, tuple) or any(not isinstance(path, Path) for path in raw):
+            from ..lib.errors.failures import AttachmentInputInvalid
+
+            raise AttachmentInputInvalid()
+        return AttachmentResolver().resolve(raw)
+
+
+__all__ = ["AgentAttachmentOptions"]

vidbyte_cli/commands/agents/__init__.py

@@ -0,0 +1,31 @@
+"""Registers the agents command family for locally run specialized agents.
+
+The `agents` group is distinct from `runtime` primitives because its commands
+are free, local, and return suggestions without executing them. This module
+owns the group and its `suggest` subgroup so the three verbs share one home.
+"""
+
+from __future__ import annotations
+
+import click
+
+
+class AgentsGroup:
+    """Attaches agents/suggest with run, categories, and handoff verbs."""
+
+    def register(self, parent: click.Group) -> None:
+        # Builds nested groups here so commands/__init__.py stays declarative.
+        from .suggestion import SuggestionAgentGroup
+
+        agents = click.Group(name="agents", help=_AGENTS_HELP)
+        SuggestionAgentGroup().register(agents)
+        parent.add_command(agents)
+
+
+_AGENTS_HELP = (
+    "Vidbyte specialized agents focus on a defined reasoning role and produce a structured "
+    "work product for a person or another agent. Each agent interprets the supplied goal "
+    "and context through the perspective needed for its specialty. The resulting analysis "
+    "makes its conclusions, supporting context, and recommended follow-up explicit. Choose "
+    "a specialized agent when a general response would leave the next decision underspecified."
+)

vidbyte_cli/commands/agents/suggestion/__init__.py

@@ -0,0 +1,38 @@
+"""Registers the suggestion agent, its run-side operations, and its project memory.
+
+The package keeps one specialized agent's command adapters together beneath
+the broader agents namespace. Registration remains side-effect free so every
+help path works without credentials, provider access, or model imports.
+"""
+
+from __future__ import annotations
+
+import click
+
+
+class SuggestionAgentGroup:
+    """Attaches run, categories, handoff, and the project and feedback memory groups."""
+
+    def register(self, parent: click.Group) -> None:
+        from .suggest import SuggestRunCommand
+        from .suggestion_categories import SuggestionCategoriesCommand
+        from .suggestion_feedback import SuggestionFeedbackGroup
+        from .suggestion_handoff import SuggestionHandoffCommand
+        from .suggestion_projects import SuggestionProjectGroup
+
+        suggest = click.Group(name="suggest", help=_SUGGEST_HELP)
+        SuggestRunCommand().register(suggest)
+        SuggestionCategoriesCommand().register(suggest)
+        SuggestionHandoffCommand().register(suggest)
+        SuggestionProjectGroup().register(suggest)
+        SuggestionFeedbackGroup().register(suggest)
+        parent.add_command(suggest)
+
+
+_SUGGEST_HELP = (
+    "The suggestion agent develops concrete next actions for a stated goal and ranks the "
+    "ones most worth pursuing. It grounds each idea in the available context, distinguishes "
+    "among different kinds of opportunity, and challenges weak or redundant candidates. "
+    "Every surviving idea explains why it matters now and carries the structure another "
+    "agent needs to evaluate decisions, evidence, considerations, and the proposed action."
+)

vidbyte_cli/commands/agents/suggestion/prompts/__init__.py

@@ -0,0 +1,3 @@
+"""Packaged help prose for the suggestion agent command surface."""
+
+from __future__ import annotations

vidbyte_cli/commands/agents/suggestion/prompts/all_categories.md

@@ -0,0 +1,5 @@
+Whole-registry consideration makes breadth an explicit part of the suggestion request. It invites every documented opportunity type without demanding one result from each type.
+
+This is already the natural behavior when no narrower category set is supplied. Making the intent explicit helps agents preserve it in durable request records.
+
+The result limit and relevance threshold still govern the final slate. Temporal focus may narrow candidates independently of category breadth.

vidbyte_cli/commands/agents/suggestion/prompts/approaches.md

@@ -0,0 +1,100 @@
+**Approach History**
+Approach History is the named previous direction value that this command accepts for one suggestion workflow.
+It gives the parent agent a stable way to state a direction that was tried, considered, accepted, or rejected.
+This value is completely optional. Supplying it is helpful when the additional signal can change the next action.
+The command keeps this value as caller task data and does not treat it as an instruction to execute work.
+The value is carried into the bounded request with its source and semantic identity intact.
+A precise value gives the generator and independent critic more signal than a broad label or an unstated assumption.
+
+**Purpose of Approach History**
+The purpose of Approach History is to make a direction that was tried, considered, accepted, or rejected explicit before candidate generation starts.
+That explicit record lets the workflow compare ideas against the situation the caller actually described.
+It also lets the critic explain whether a candidate is supported, missing evidence, or in conflict.
+The field is most valuable when its content changes feasibility, novelty, timing, risk, or the definition of progress.
+A short accurate statement is more useful than a long narrative that hides the decision-relevant fact.
+The resulting ideas should refer to this signal only when the connection is material and explain why it matters.
+
+**When not to use Approach History**
+Do not provide Approach History merely because the option exists or because an empty value would look complete.
+Omit it when the caller has no reliable signal of this kind and let the workflow mark the context as missing.
+Do not use this field to smuggle execution instructions, credentials, private data, or a second command configuration.
+Use a narrower context option when the statement has a clearly different meaning such as a risk, decision, or prohibition.
+Avoid repeating the goal or copying an entire unrelated transcript because repetition lowers the signal available to the critic.
+If the caller is unsure whether the record is current, state that uncertainty in the value rather than presenting it as a fact.
+
+**Approach History inputs**
+The value is one nonempty text statement per repeated option.
+Repeated occurrences remain separate records so the agent can cite and compare them without parsing a delimiter.
+Whitespace around a value is trimmed at the request boundary, while an empty value is rejected before provider work.
+The command does not reinterpret the content as an identifier unless the option contract explicitly says it is one.
+Use plain caller-readable text and keep each record focused on one fact, choice, boundary, or result.
+The input is bounded before it enters the agent context so oversized content becomes an explicit truncation or omission.
+A caller should keep related facts separate when their provenance, confidence, or expected effect differs enough to influence review.
+
+**Defaults and precedence for Approach History**
+When it is omitted, the default is no supplied previous direction..
+Command-line values are the only source for this field, and the run does not read a separate configuration document.
+Environment variables do not silently populate this context value, which keeps an invocation reproducible.
+When multiple values are supplied, their command-line order becomes their stable context order.
+Explicit caller input therefore takes precedence over absence, while other settings such as count and rounds remain independent.
+The result manifest records what was supplied and whether the bounded value was included, truncated, or omitted.
+Use the manifest and warnings to distinguish absence from an explicitly bounded value when a downstream agent needs to explain why a suggestion changed.
+
+**Approach History output contract**
+Approach History is not printed as a separate progress message because stdout is reserved for the command result.
+For a model-backed run, the value appears inside the fresh managed context window used by the relevant agent.
+For dry-run output, the manifest exposes source identity and bounded character information without exposing file bodies by default.
+Human output summarizes the resulting suggestions, while JSON and JSONL output preserve stable machine-readable fields.
+Errors go to the CLI error channel as typed envelopes with a repair-oriented description and no secret echo.
+The field influences ideas and handoffs but never grants authority, starts work, or changes the caller's permissions.
+
+**How to use Approach History**
+Use the command below as the smallest valid invocation shape for this value.
+Replace each brace-delimited placeholder with the caller's actual text while preserving shell quoting around spaces.
+Repeat the option when more than one independent record should be supplied.
+Combine the option with a precise goal because the field is evidence or context rather than a standalone task.
+Add category and budget options only when they answer a real selection or resource question.
+The command remains a single argv-built request and does not require a temporary configuration file.
+Keep the invocation close to the caller's actual decision so another agent can reproduce the request without guessing omitted context, quoting, or precedence.
+
+```text
+vidbyte-cli agents suggest run --goal "{goal}" --approaches "{previous direction}"
+```
+
+**Examples for Approach History**
+A minimal example supplies only the required goal and leaves this optional signal absent when it has no value.
+A normal example adds one focused record that directly changes how the next action should be judged.
+An advanced example repeats the option for several independent records and combines it with a selected category.
+Piping is appropriate only for a caller that captures the emitted result document, because input itself is passed through argv.
+JSON output is the stable choice when another agent will inspect identifiers, manifests, warnings, and handoffs.
+If an example fails, preserve the same goal and correct the named input or path before changing the reasoning settings.
+
+```text
+vidbyte-cli agents suggest run --goal "{goal}" --approaches "{previous direction}"
+vidbyte-cli --json agents suggest run --goal "{goal}" --approaches "{value}"
+```
+
+**Related commands for Approach History**
+Use agents suggest categories --view-all when the caller needs to choose a reasoning lens before running.
+Use agents suggest categories --view {category-id} when one category needs a fuller conceptual definition.
+Use the other context options when the signal is more accurately a decision, constraint, risk, or current commitment.
+Use agents suggest handoff only after a result document exists and a specific idea identifier has been selected.
+Use dry-run when the request shape and file manifest need inspection without credentials or model usage.
+These commands share the same result conventions but do not imply that one command can authorize another.
+Choose the narrowest neighboring command that answers the immediate question, then return to this option when the run itself needs the signal.
+
+**Failure modes for Approach History**
+A missing required value fails before the provider is loaded because the request dataclass requires a meaningful boundary.
+An empty repeated value fails as invalid input instead of becoming a misleading blank context record.
+An unsupported path, malformed JSON file, directory, or unreadable file fails with a typed context error.
+An oversized value is truncated only within the documented bound and the result records that status as a warning.
+A provider or schema failure is reported as a provider failure and is never converted into a false no-suggestions result.
+Recover by correcting the specific value named by the error, rerunning dry-run when useful, and preserving the same intent.
+
+**Authentication and permissions for Approach History**
+This input itself does not grant access to files, providers, accounts, repositories, or execution tools.
+Text values are available to local validation without credentials, while model-backed runs still require the configured provider.
+The --files option reads only paths explicitly named by the caller and does not scan a workspace or agent history.
+Read-only deny-all settings apply to generator and critic agents so suggestions cannot mutate the host through this workflow.
+Provider credentials are used only when a real model-backed run is requested and are never copied into result prose.
+Permission failures should be repaired at the provider or filesystem boundary rather than by weakening the context contract.

vidbyte_cli/commands/agents/suggestion/prompts/avoid.md

@@ -0,0 +1,100 @@
+**Directions to Avoid**
+Directions to Avoid is the named rejected direction value that this command accepts for one suggestion workflow.
+It gives the parent agent a stable way to state an approach or direction the caller does not want proposed.
+This value is completely optional. Supplying it is helpful when the additional signal can change the next action.
+The command keeps this value as caller task data and does not treat it as an instruction to execute work.
+The value is carried into the bounded request with its source and semantic identity intact.
+A precise value gives the generator and independent critic more signal than a broad label or an unstated assumption.
+
+**Purpose of Directions to Avoid**
+The purpose of Directions to Avoid is to make an approach or direction the caller does not want proposed explicit before candidate generation starts.
+That explicit record lets the workflow compare ideas against the situation the caller actually described.
+It also lets the critic explain whether a candidate is supported, missing evidence, or in conflict.
+The field is most valuable when its content changes feasibility, novelty, timing, risk, or the definition of progress.
+A short accurate statement is more useful than a long narrative that hides the decision-relevant fact.
+The resulting ideas should refer to this signal only when the connection is material and explain why it matters.
+
+**When not to use Directions to Avoid**
+Do not provide Directions to Avoid merely because the option exists or because an empty value would look complete.
+Omit it when the caller has no reliable signal of this kind and let the workflow mark the context as missing.
+Do not use this field to smuggle execution instructions, credentials, private data, or a second command configuration.
+Use a narrower context option when the statement has a clearly different meaning such as a risk, decision, or prohibition.
+Avoid repeating the goal or copying an entire unrelated transcript because repetition lowers the signal available to the critic.
+If the caller is unsure whether the record is current, state that uncertainty in the value rather than presenting it as a fact.
+
+**Directions to Avoid inputs**
+The value is one nonempty text statement per repeated option.
+Repeated occurrences remain separate records so the agent can cite and compare them without parsing a delimiter.
+Whitespace around a value is trimmed at the request boundary, while an empty value is rejected before provider work.
+The command does not reinterpret the content as an identifier unless the option contract explicitly says it is one.
+Use plain caller-readable text and keep each record focused on one fact, choice, boundary, or result.
+The input is bounded before it enters the agent context so oversized content becomes an explicit truncation or omission.
+A caller should keep related facts separate when their provenance, confidence, or expected effect differs enough to influence review.
+
+**Defaults and precedence for Directions to Avoid**
+When it is omitted, the default is no supplied rejected direction..
+Command-line values are the only source for this field, and the run does not read a separate configuration document.
+Environment variables do not silently populate this context value, which keeps an invocation reproducible.
+When multiple values are supplied, their command-line order becomes their stable context order.
+Explicit caller input therefore takes precedence over absence, while other settings such as count and rounds remain independent.
+The result manifest records what was supplied and whether the bounded value was included, truncated, or omitted.
+Use the manifest and warnings to distinguish absence from an explicitly bounded value when a downstream agent needs to explain why a suggestion changed.
+
+**Directions to Avoid output contract**
+Directions to Avoid is not printed as a separate progress message because stdout is reserved for the command result.
+For a model-backed run, the value appears inside the fresh managed context window used by the relevant agent.
+For dry-run output, the manifest exposes source identity and bounded character information without exposing file bodies by default.
+Human output summarizes the resulting suggestions, while JSON and JSONL output preserve stable machine-readable fields.
+Errors go to the CLI error channel as typed envelopes with a repair-oriented description and no secret echo.
+The field influences ideas and handoffs but never grants authority, starts work, or changes the caller's permissions.
+
+**How to use Directions to Avoid**
+Use the command below as the smallest valid invocation shape for this value.
+Replace each brace-delimited placeholder with the caller's actual text while preserving shell quoting around spaces.
+Repeat the option when more than one independent record should be supplied.
+Combine the option with a precise goal because the field is evidence or context rather than a standalone task.
+Add category and budget options only when they answer a real selection or resource question.
+The command remains a single argv-built request and does not require a temporary configuration file.
+Keep the invocation close to the caller's actual decision so another agent can reproduce the request without guessing omitted context, quoting, or precedence.
+
+```text
+vidbyte-cli agents suggest run --goal "{goal}" --avoid "{direction to avoid}"
+```
+
+**Examples for Directions to Avoid**
+A minimal example supplies only the required goal and leaves this optional signal absent when it has no value.
+A normal example adds one focused record that directly changes how the next action should be judged.
+An advanced example repeats the option for several independent records and combines it with a selected category.
+Piping is appropriate only for a caller that captures the emitted result document, because input itself is passed through argv.
+JSON output is the stable choice when another agent will inspect identifiers, manifests, warnings, and handoffs.
+If an example fails, preserve the same goal and correct the named input or path before changing the reasoning settings.
+
+```text
+vidbyte-cli agents suggest run --goal "{goal}" --avoid "{direction to avoid}"
+vidbyte-cli --json agents suggest run --goal "{goal}" --avoid "{value}"
+```
+
+**Related commands for Directions to Avoid**
+Use agents suggest categories --view-all when the caller needs to choose a reasoning lens before running.
+Use agents suggest categories --view {category-id} when one category needs a fuller conceptual definition.
+Use the other context options when the signal is more accurately a decision, constraint, risk, or current commitment.
+Use agents suggest handoff only after a result document exists and a specific idea identifier has been selected.
+Use dry-run when the request shape and file manifest need inspection without credentials or model usage.
+These commands share the same result conventions but do not imply that one command can authorize another.
+Choose the narrowest neighboring command that answers the immediate question, then return to this option when the run itself needs the signal.
+
+**Failure modes for Directions to Avoid**
+A missing required value fails before the provider is loaded because the request dataclass requires a meaningful boundary.
+An empty repeated value fails as invalid input instead of becoming a misleading blank context record.
+An unsupported path, malformed JSON file, directory, or unreadable file fails with a typed context error.
+An oversized value is truncated only within the documented bound and the result records that status as a warning.
+A provider or schema failure is reported as a provider failure and is never converted into a false no-suggestions result.
+Recover by correcting the specific value named by the error, rerunning dry-run when useful, and preserving the same intent.
+
+**Authentication and permissions for Directions to Avoid**
+This input itself does not grant access to files, providers, accounts, repositories, or execution tools.
+Text values are available to local validation without credentials, while model-backed runs still require the configured provider.
+The --files option reads only paths explicitly named by the caller and does not scan a workspace or agent history.
+Read-only deny-all settings apply to generator and critic agents so suggestions cannot mutate the host through this workflow.
+Provider credentials are used only when a real model-backed run is requested and are never copied into result prose.
+Permission failures should be repaired at the provider or filesystem boundary rather than by weakening the context contract.

vidbyte_cli/commands/agents/suggestion/prompts/blockers.md

@@ -0,0 +1,100 @@
+**Blockers**
+Blockers is the named blocking condition value that this command accepts for one suggestion workflow.
+It gives the parent agent a stable way to state a condition that currently prevents or delays useful progress.
+This value is completely optional. Supplying it is helpful when the additional signal can change the next action.
+The command keeps this value as caller task data and does not treat it as an instruction to execute work.
+The value is carried into the bounded request with its source and semantic identity intact.
+A precise value gives the generator and independent critic more signal than a broad label or an unstated assumption.
+
+**Purpose of Blockers**
+The purpose of Blockers is to make a condition that currently prevents or delays useful progress explicit before candidate generation starts.
+That explicit record lets the workflow compare ideas against the situation the caller actually described.
+It also lets the critic explain whether a candidate is supported, missing evidence, or in conflict.
+The field is most valuable when its content changes feasibility, novelty, timing, risk, or the definition of progress.
+A short accurate statement is more useful than a long narrative that hides the decision-relevant fact.
+The resulting ideas should refer to this signal only when the connection is material and explain why it matters.
+
+**When not to use Blockers**
+Do not provide Blockers merely because the option exists or because an empty value would look complete.
+Omit it when the caller has no reliable signal of this kind and let the workflow mark the context as missing.
+Do not use this field to smuggle execution instructions, credentials, private data, or a second command configuration.
+Use a narrower context option when the statement has a clearly different meaning such as a risk, decision, or prohibition.
+Avoid repeating the goal or copying an entire unrelated transcript because repetition lowers the signal available to the critic.
+If the caller is unsure whether the record is current, state that uncertainty in the value rather than presenting it as a fact.
+
+**Blockers inputs**
+The value is one nonempty text statement per repeated option.
+Repeated occurrences remain separate records so the agent can cite and compare them without parsing a delimiter.
+Whitespace around a value is trimmed at the request boundary, while an empty value is rejected before provider work.
+The command does not reinterpret the content as an identifier unless the option contract explicitly says it is one.
+Use plain caller-readable text and keep each record focused on one fact, choice, boundary, or result.
+The input is bounded before it enters the agent context so oversized content becomes an explicit truncation or omission.
+A caller should keep related facts separate when their provenance, confidence, or expected effect differs enough to influence review.
+
+**Defaults and precedence for Blockers**
+When it is omitted, the default is no supplied blocking condition..
+Command-line values are the only source for this field, and the run does not read a separate configuration document.
+Environment variables do not silently populate this context value, which keeps an invocation reproducible.
+When multiple values are supplied, their command-line order becomes their stable context order.
+Explicit caller input therefore takes precedence over absence, while other settings such as count and rounds remain independent.
+The result manifest records what was supplied and whether the bounded value was included, truncated, or omitted.
+Use the manifest and warnings to distinguish absence from an explicitly bounded value when a downstream agent needs to explain why a suggestion changed.
+
+**Blockers output contract**
+Blockers is not printed as a separate progress message because stdout is reserved for the command result.
+For a model-backed run, the value appears inside the fresh managed context window used by the relevant agent.
+For dry-run output, the manifest exposes source identity and bounded character information without exposing file bodies by default.
+Human output summarizes the resulting suggestions, while JSON and JSONL output preserve stable machine-readable fields.
+Errors go to the CLI error channel as typed envelopes with a repair-oriented description and no secret echo.
+The field influences ideas and handoffs but never grants authority, starts work, or changes the caller's permissions.
+
+**How to use Blockers**
+Use the command below as the smallest valid invocation shape for this value.
+Replace each brace-delimited placeholder with the caller's actual text while preserving shell quoting around spaces.
+Repeat the option when more than one independent record should be supplied.
+Combine the option with a precise goal because the field is evidence or context rather than a standalone task.
+Add category and budget options only when they answer a real selection or resource question.
+The command remains a single argv-built request and does not require a temporary configuration file.
+Keep the invocation close to the caller's actual decision so another agent can reproduce the request without guessing omitted context, quoting, or precedence.
+
+```text
+vidbyte-cli agents suggest run --goal "{goal}" --blockers "{blocking condition}"
+```
+
+**Examples for Blockers**
+A minimal example supplies only the required goal and leaves this optional signal absent when it has no value.
+A normal example adds one focused record that directly changes how the next action should be judged.
+An advanced example repeats the option for several independent records and combines it with a selected category.
+Piping is appropriate only for a caller that captures the emitted result document, because input itself is passed through argv.
+JSON output is the stable choice when another agent will inspect identifiers, manifests, warnings, and handoffs.
+If an example fails, preserve the same goal and correct the named input or path before changing the reasoning settings.
+
+```text
+vidbyte-cli agents suggest run --goal "{goal}" --blockers "{blocking condition}"
+vidbyte-cli --json agents suggest run --goal "{goal}" --blockers "{value}"
+```
+
+**Related commands for Blockers**
+Use agents suggest categories --view-all when the caller needs to choose a reasoning lens before running.
+Use agents suggest categories --view {category-id} when one category needs a fuller conceptual definition.
+Use the other context options when the signal is more accurately a decision, constraint, risk, or current commitment.
+Use agents suggest handoff only after a result document exists and a specific idea identifier has been selected.
+Use dry-run when the request shape and file manifest need inspection without credentials or model usage.
+These commands share the same result conventions but do not imply that one command can authorize another.
+Choose the narrowest neighboring command that answers the immediate question, then return to this option when the run itself needs the signal.
+
+**Failure modes for Blockers**
+A missing required value fails before the provider is loaded because the request dataclass requires a meaningful boundary.
+An empty repeated value fails as invalid input instead of becoming a misleading blank context record.
+An unsupported path, malformed JSON file, directory, or unreadable file fails with a typed context error.
+An oversized value is truncated only within the documented bound and the result records that status as a warning.
+A provider or schema failure is reported as a provider failure and is never converted into a false no-suggestions result.
+Recover by correcting the specific value named by the error, rerunning dry-run when useful, and preserving the same intent.
+
+**Authentication and permissions for Blockers**
+This input itself does not grant access to files, providers, accounts, repositories, or execution tools.
+Text values are available to local validation without credentials, while model-backed runs still require the configured provider.
+The --files option reads only paths explicitly named by the caller and does not scan a workspace or agent history.
+Read-only deny-all settings apply to generator and critic agents so suggestions cannot mutate the host through this workflow.
+Provider credentials are used only when a real model-backed run is requested and are never copied into result prose.
+Permission failures should be repaired at the provider or filesystem boundary rather than by weakening the context contract.