vidbyte-cli 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,100 @@
+**Forbidden Actions**
+Forbidden Actions is the named prohibited action value that this command accepts for one suggestion workflow.
+It gives the parent agent a stable way to state an action that must not be proposed or taken for this goal.
+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 Forbidden Actions**
+The purpose of Forbidden Actions is to make an action that must not be proposed or taken for this goal 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 Forbidden Actions**
+Do not provide Forbidden Actions 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.
+
+**Forbidden Actions 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 Forbidden Actions**
+When it is omitted, the default is no supplied prohibited action..
+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.
+
+**Forbidden Actions output contract**
+Forbidden Actions 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 Forbidden Actions**
+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}" --forbidden "{prohibited action}"
+```
+
+**Examples for Forbidden Actions**
+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}" --forbidden "{prohibited action}"
+vidbyte-cli --json agents suggest run --goal "{goal}" --forbidden "{value}"
+```
+
+**Related commands for Forbidden Actions**
+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 Forbidden Actions**
+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 Forbidden Actions**
+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/goal.md

@@ -0,0 +1,100 @@
+**Goal**
+Goal is the named goal value that this command accepts for one suggestion workflow.
+It gives the parent agent a stable way to state the outcome the caller wants the suggestion agent to advance.
+This value is required for a run. 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 Goal**
+The purpose of Goal is to make the outcome the caller wants the suggestion agent to advance 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 Goal**
+Do not provide Goal 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.
+
+**Goal inputs**
+The value is one trimmed nonempty string up to 4096 characters.
+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 Goal**
+There is no useful implicit goal because the agent cannot infer the caller's intended outcome safely..
+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.
+
+**Goal output contract**
+Goal 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 Goal**
+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}"
+```
+
+**Examples for Goal**
+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}"
+vidbyte-cli --json agents suggest run --goal "{goal}" --goal "{value}"
+```
+
+**Related commands for Goal**
+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 Goal**
+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 Goal**
+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/handoff.md

@@ -0,0 +1,7 @@
+A handoff extracts one reviewed idea from a saved suggestion result and emits a deterministic action packet. It is a local read operation for callers that want to pass one selected idea to a person or another agent.
+
+The command requires both a result path and an exact idea identifier. It validates the saved envelope before selecting the idea and never accepts a title, prefix, or fuzzy match as a substitute for the stable identifier.
+
+No provider, credential, or execution permission is needed for extraction. JSON output preserves the handoff fields, while human output prints the copyable execution prompt and the packet itself never grants authority.
+
+Use this command after a run has produced a result document. If selection or validation fails, correct the saved path or identifier and rerun the same request rather than treating an absent handoff as a provider failure.

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

@@ -0,0 +1,5 @@
+The horizon describes when a suggestion should become useful: immediately, next in sequence, later, or without a temporal restriction. An unrestricted horizon supports a deliberate mix across time.
+
+A narrower horizon helps when timing matters more than broad opportunity discovery. Each returned idea still records its concrete horizon for inspection.
+
+Temporal focus changes selection rather than the underlying goal. Unsupported horizon values are rejected before any candidate reasoning begins.

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

@@ -0,0 +1,100 @@
+**Hypotheses**
+Hypotheses is the named testable belief value that this command accepts for one suggestion workflow.
+It gives the parent agent a stable way to state a belief about the goal or current state that may need evidence.
+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 Hypotheses**
+The purpose of Hypotheses is to make a belief about the goal or current state that may need evidence 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 Hypotheses**
+Do not provide Hypotheses 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.
+
+**Hypotheses 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 Hypotheses**
+When it is omitted, the default is no supplied testable belief..
+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.
+
+**Hypotheses output contract**
+Hypotheses 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 Hypotheses**
+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}" --hypotheses "{testable belief}"
+```
+
+**Examples for Hypotheses**
+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}" --hypotheses "{testable belief}"
+vidbyte-cli --json agents suggest run --goal "{goal}" --hypotheses "{value}"
+```
+
+**Related commands for Hypotheses**
+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 Hypotheses**
+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 Hypotheses**
+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/idea.md

@@ -0,0 +1,100 @@
+**Idea Identifier**
+Idea Identifier is the named stable idea identifier value that this command accepts for one suggestion workflow.
+It gives the parent agent a stable way to state the exact identifier of one idea inside a saved suggestions.result document.
+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 Idea Identifier**
+The purpose of Idea Identifier is to make the exact identifier of one idea inside a saved suggestions.result document 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 Idea Identifier**
+Do not provide Idea Identifier 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.
+
+**Idea Identifier inputs**
+The value is one identifier such as idea-003.
+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 Idea Identifier**
+When it is omitted, the default is no supplied stable idea identifier..
+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.
+
+**Idea Identifier output contract**
+Idea Identifier 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 Idea Identifier**
+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 handoff --input "{result.json}" --idea "{idea-id}"
+```
+
+**Examples for Idea Identifier**
+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 handoff --input "{result.json}" --idea "{idea-id}"
+vidbyte-cli --json agents suggest run --goal "{goal}" --idea "{value}"
+```
+
+**Related commands for Idea Identifier**
+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 Idea Identifier**
+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 Idea Identifier**
+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/in_progress.md

@@ -0,0 +1,100 @@
+**In-Progress Work**
+In-Progress Work is the named current commitment value that this command accepts for one suggestion workflow.
+It gives the parent agent a stable way to state work that has started but is not yet finished.
+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 In-Progress Work**
+The purpose of In-Progress Work is to make work that has started but is not yet finished 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 In-Progress Work**
+Do not provide In-Progress Work 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.
+
+**In-Progress Work 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 In-Progress Work**
+When it is omitted, the default is no supplied current commitment..
+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.
+
+**In-Progress Work output contract**
+In-Progress Work 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 In-Progress Work**
+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}" --in-progress "{current commitment}"
+```
+
+**Examples for In-Progress Work**
+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}" --in-progress "{current commitment}"
+vidbyte-cli --json agents suggest run --goal "{goal}" --in-progress "{value}"
+```
+
+**Related commands for In-Progress Work**
+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 In-Progress Work**
+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 In-Progress Work**
+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.