vidbyte-cli 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,96 @@
+**Project key**
+Project key is the unique identifier this command registers for a new local suggestion project.
+It is the one value every later command uses to address the project, including feedback accept, feedback reject, and a suggestion run with the project option.
+The key also names the project's memory file on disk, which is why its character set is deliberately narrow.
+Choose it once and keep it stable, because a project cannot be renamed and a new key starts an empty feedback history.
+A good key is short and names the body of work, such as a repository, product area, or long-running goal, rather than a single run.
+The command stores the key exactly as validated, so the value a caller passes later must match it character for character.
+
+**Purpose of Project key**
+The purpose of Project key is to give a parent agent a stable handle it can store, pass between sessions, and paste into later commands without ambiguity.
+Titles and descriptions are free prose that may change in meaning or wording, while the key is the exact selector the catalog compares.
+Keeping identity separate from description lets the title read naturally for a person while the key stays safe for scripts and file names.
+The key is what makes feedback cumulative, because every reaction recorded under the same key lands in the same ordered history.
+A predictable key also lets an agent that lost its transcript recover the project from project list instead of creating a duplicate.
+That recovery is only reliable when the key names the work plainly enough for an agent to recognize it later.
+
+**When not to use Project key**
+Do not register a new key for work that already has a project, because feedback split across two keys is never merged and each run sees only half of it.
+Do not encode dates, run numbers, or session identifiers in the key unless the project truly is scoped to that period.
+Avoid keys that describe a single suggestion or idea, since a project is meant to collect many reactions over time.
+Do not place private data, credentials, or customer names in the key, because it appears in listings, result documents, and file names.
+Do not rely on case or punctuation to distinguish two projects, since uppercase letters and punctuation other than hyphens and underscores are rejected.
+If you are unsure whether a suitable project exists, run project list before creating anything new.
+
+**Project key inputs**
+The value is one string of 1 to 64 characters drawn from lowercase letters, numbers, hyphens, and underscores.
+The first character must be a lowercase letter or a number, so a key cannot begin with a hyphen or an underscore.
+Whitespace around the value is trimmed before validation, and whitespace inside the key is rejected.
+Slashes, dots, and other path characters are rejected outright, which keeps the key from ever naming a location outside the project directory.
+The option is required, so the command refuses to run without it before reading any file.
+Validation happens in the command's input dataclass, before the catalog is opened, so an invalid key never touches disk.
+
+**Defaults and precedence for Project key**
+There is no default key, because the CLI cannot guess which body of work the caller means.
+The value comes only from this command-line option and is never read from an environment variable or a configuration file.
+A key that already exists in the catalog is refused rather than overwritten, so creation never silently replaces an existing project or its history.
+A leftover memory file with the same name is also treated as an existing project, which protects feedback that outlived a damaged catalog entry.
+The trimmed key is the canonical form, and the same trimming is applied wherever a key is accepted later.
+No other option can change the key after creation, and there is no rename command in this version.
+
+**Project key output contract**
+On success the command returns a suggestions.project.created document whose data holds the key, title, description, and linked memory file.
+Human output prints a single confirmation line naming the created key.
+The memory file link is always the relative path projects slash key dot json inside the suggestion data directory, and it is recorded in the catalog.
+The command writes the memory file before it publishes the catalog entry, so a listed project always has a readable memory file.
+If publishing the catalog fails, the new memory file is removed again so the same key can be retried cleanly.
+Errors go to the error channel as typed envelopes, and stdout stays empty when creation fails.
+
+**How to use Project key**
+Pick a short lowercase name for the work the suggestions will be about, joining words with hyphens.
+Pass it together with a title and a description in one project create call.
+Save the key wherever the parent agent keeps durable notes, because every later feedback call and project run needs it.
+Reuse the same key for every run and every reaction about that work rather than creating a new project per session.
+If a create call reports that the key exists, list the projects and decide whether the existing one is the right scope before choosing another key.
+Keep the key free of secrets, since it is printed in listings and embedded in the feedback commands a run returns.
+
+```text
+vidbyte-cli agents suggest project create --key "{project-key}" --title "{title}" --description "{description}"
+```
+
+**Examples for Project key**
+A repository-scoped key such as vidbyte-cli collects every reaction about suggestions for that one codebase.
+A goal-scoped key such as q3-onboarding collects reactions about a single long-running objective that spans several repositories.
+An area-scoped key such as billing_api narrows memory to one component when feedback about neighbouring areas would mislead the generator.
+A rejected example is a key with uppercase letters or a slash, which fails before anything is written and can simply be retyped.
+JSON output returns the created key in the document data, which is the value to store for later calls.
+If a key collides with an existing project, choose a more specific key only after confirming the existing project is not the right one.
+
+```text
+vidbyte-cli agents suggest project create --key "{project-key}" --title "{title}" --description "{description}"
+vidbyte-cli --json agents suggest project create --key "{project-key}" --title "{title}" --description "{description}"
+```
+
+**Related commands for Project key**
+Use agents suggest project list to see every registered key before creating a new one.
+Use agents suggest run with the project option and this key to load the project's memory into a suggestion run.
+Use agents suggest feedback accept with this key to record a suggestion the user explicitly wanted.
+Use agents suggest feedback reject with this key to record a suggestion the user explicitly refused.
+The key is the only value these commands share, so an exact match is what connects them.
+None of these commands creates a project implicitly, which is why creation with this key must come first.
+
+**Failure modes for Project key**
+A missing key fails as a usage error before any validation of the other fields.
+A key that is too long, begins with a hyphen or underscore, or contains uppercase or path characters fails as an invalid project.
+A key already present in the catalog fails as an existing project and leaves the existing entry and its feedback untouched.
+A memory file already present under the key's name also fails as an existing project rather than being replaced.
+An unreadable or malformed catalog fails as unreadable project state, because adding to a broken catalog could discard the projects it lists.
+Recover by correcting the key's characters, choosing an unused key, or repairing the named invalid file before retrying.
+
+**Authentication and permissions for Project key**
+Creating a project requires no Vidbyte login, API key, or model provider.
+The key is written only to the local catalog and memory file inside the platform-native Vidbyte data directory.
+Nothing about the key is sent to Vidbyte or to any provider by this command.
+The command needs permission to create and replace files in that data directory, and it reports a write failure when the filesystem refuses.
+A key grants no permission of its own, and knowing a key does not let a caller do anything beyond reading or appending to that local project.
+Repair permission problems at the data directory rather than by choosing a different key.

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

@@ -0,0 +1,7 @@
+Project list prints every local suggestion project registered in the catalog, sorted by key. Each entry shows the key, the title, and the description, which is enough to choose the right project for a run or a feedback call without opening any memory file.
+
+Use it at the start of a session that does not remember which projects exist, before creating a new project to avoid a duplicate, and whenever a feedback or run command reports an unknown key. The listing reads only the catalog, so it never loads feedback bodies and stays fast however long a project's history grows.
+
+An absent catalog means no project has been created yet and returns an empty successful result rather than an error. A catalog that exists but is malformed, unreadable, or in an unsupported schema fails as unreadable project state, because treating it as empty would hide projects that still have feedback on disk.
+
+The command needs no credentials and makes no model call. JSON output returns a projects array whose entries carry key, title, description, and memory_file, while human output prints one block per project.

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

@@ -0,0 +1,99 @@
+**Project title**
+Project title is the short human-readable name stored with a new local suggestion project.
+It is what a person or parent agent reads in project list output to recognize which body of work a key refers to.
+The title is also loaded into the context of every project-backed run, so the generator knows which work the recorded feedback belongs to.
+It is descriptive metadata only and does not select, authorize, or configure anything by itself.
+A title should be recognizable at a glance, such as a product name, a repository name, or the plain name of a long-running goal.
+The command keeps the title verbatim apart from trimming surrounding whitespace, so the stored wording is exactly what the caller supplied.
+
+**Purpose of Project title**
+The purpose of Project title is to make a project identifiable to readers who never saw the command that created it.
+Keys are constrained to lowercase identifiers, while a title can use natural capitalization, spaces, and punctuation that make the scope obvious.
+In a suggestion run the title appears as a labelled context line, which helps the generator connect stored reactions to the right work.
+In a listing the title sits next to the key, which lets an agent without a transcript choose the correct project instead of creating a duplicate.
+A precise title reduces the chance that feedback from one project is mistaken for guidance about another.
+It complements the description, which carries scope, by giving that scope a short memorable name.
+
+**When not to use Project title**
+Do not use the title to hold instructions to the model, because it is loaded as data and never treated as a directive.
+Do not repeat the whole description in the title, since the description field already carries scope and a long title makes listings hard to scan.
+Avoid titles that only restate the key in different casing, because they add no information a reader could use.
+Do not include credentials, private personal data, or confidential customer details, since the title appears in listings and in run context.
+Avoid temporary phrasing such as this week's plan unless the project truly ends when that period ends.
+If the right name is still unclear, create the project with a plain working title rather than inventing a misleading one.
+
+**Project title inputs**
+The value is one nonempty string of at most 200 characters after surrounding whitespace is trimmed.
+Spaces, capital letters, digits, and ordinary punctuation are all accepted inside the title.
+A value made only of whitespace is rejected, because an empty title would make the project unrecognizable in listings.
+The option is required, so creation refuses to run without a title.
+Validation happens in the command's input dataclass together with the key and description, before the catalog is read.
+The title is stored as plain text and is never parsed, templated, or reinterpreted as a selector.
+Because the title is loaded on every project-backed run, a short title also leaves more of the shared context budget for feedback.
+
+**Defaults and precedence for Project title**
+There is no default title, because only the caller knows how the project should be named for its readers.
+The value comes only from this option and is never taken from an environment variable, a configuration file, or the key.
+Trimming surrounding whitespace is the only normalization applied, so capitalization and internal punctuation are preserved exactly.
+The title is fixed at creation in this version, and there is no command that edits it afterwards.
+The key, not the title, is what every other command compares, so two projects may share a title without conflict.
+Sharing a title is still discouraged because it makes listings ambiguous for a reader choosing between keys.
+
+**Project title output contract**
+On success the created document's data includes the title exactly as stored after trimming.
+Project list prints the title next to each key in human output and includes it as a field in JSON output.
+A project-backed suggestion run includes the title as a context line labelled Project title within the project context kind.
+The title is recorded in the result manifest only as part of that context item, with its size and inclusion status.
+The title never appears in the file name of the memory document, which is derived from the key alone.
+Errors about the title are reported as an invalid project without echoing the rejected value.
+
+**How to use Project title**
+Write a short name a teammate would recognize without further explanation.
+Pass it in quotes together with the key and description in one project create call.
+Prefer the name the work is already known by, such as the repository or product name, over a new invented label.
+Keep it under a line so project list output remains easy to scan when several projects exist.
+Put detail about scope, boundaries, and goals in the description rather than lengthening the title.
+Check the stored title with project list after creation if another agent will rely on it later.
+Because the title cannot be edited later in this version, a moment spent choosing a clear name saves confusion for every later reader.
+
+```text
+vidbyte-cli agents suggest project create --key "{project-key}" --title "{title}" --description "{description}"
+```
+
+**Examples for Project title**
+A repository example uses a title such as Vidbyte CLI for a project keyed vidbyte-cli.
+A goal example uses a title such as Q3 onboarding revamp for a project that spans several components.
+A component example uses a title such as Billing API for a project limited to one service.
+A weak example uses a title identical to the key, which works but tells a reader nothing new.
+JSON output returns the stored title in the created document, which confirms trimming behaved as expected.
+If creation fails because of the title, supply a nonempty value within the length bound and retry with the same key.
+
+```text
+vidbyte-cli agents suggest project create --key "{project-key}" --title "{title}" --description "{description}"
+vidbyte-cli --json agents suggest project list
+```
+
+**Related commands for Project title**
+Use agents suggest project list to read every stored title next to its key.
+Use agents suggest run with the project option to load this title into a run's context as part of the project item.
+Use the description option of project create to state the project's scope in full sentences.
+Use agents suggest feedback accept and reject with the key, not the title, because the key is the selector.
+The title and key are always created together and cannot be changed independently in this version.
+None of these related commands needs credentials to read the title.
+Choosing the right project from its title and description before a feedback call keeps each reaction in the scope it was really about.
+
+**Failure modes for Project title**
+A missing title fails as a usage error before any file is read.
+A title that is empty after trimming fails as an invalid project and nothing is written.
+A title longer than 200 characters fails as an invalid project with the bound named in the error.
+A title that is valid never fails on its own content, because its wording is not interpreted.
+Creation can still fail for reasons unrelated to the title, such as an existing key or an unwritable data directory.
+Recover from a title failure by shortening or filling in the value and repeating the same create call.
+
+**Authentication and permissions for Project title**
+Supplying a title requires no Vidbyte login, API key, or provider credential.
+The title is stored only in the local project catalog inside the platform-native Vidbyte data directory.
+It leaves the machine only when a model-backed run with the project option sends its context to the configured provider.
+Dry runs and listings read the title locally and send nothing anywhere.
+The title grants no permission to any agent and cannot widen what a generator or critic may do.
+Keep sensitive material out of the title because it is shared with the provider whenever the project is used in a real run.

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

@@ -0,0 +1,5 @@
+The provider identifies the configured model service responsible for suggestion reasoning. Explicit selection makes the source of generated and reviewed output reproducible.
+
+The provider must correspond to a supported SDK integration and available credentials. Invalid or unavailable selections fail as provider configuration problems rather than empty suggestion results.
+
+Provider choice does not alter schemas, categories, or context meaning. When none is selected, the established default behavior remains in effect.

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

@@ -0,0 +1,100 @@
+**Open Questions**
+Open Questions is the named unresolved question value that this command accepts for one suggestion workflow.
+It gives the parent agent a stable way to state an uncertainty that a useful next action should answer or narrow.
+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 Open Questions**
+The purpose of Open Questions is to make an uncertainty that a useful next action should answer or narrow 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 Open Questions**
+Do not provide Open Questions 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.
+
+**Open Questions 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 Open Questions**
+When it is omitted, the default is no supplied unresolved question..
+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.
+
+**Open Questions output contract**
+Open Questions 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 Open Questions**
+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}" --question "{open question}"
+```
+
+**Examples for Open Questions**
+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}" --question "{open question}"
+vidbyte-cli --json agents suggest run --goal "{goal}" --question "{value}"
+```
+
+**Related commands for Open Questions**
+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 Open Questions**
+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 Open Questions**
+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/risks.md

@@ -0,0 +1,100 @@
+**Risks**
+Risks is the named plausible exposure value that this command accepts for one suggestion workflow.
+It gives the parent agent a stable way to state a plausible harm, failure mode, or exposure around the 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 Risks**
+The purpose of Risks is to make a plausible harm, failure mode, or exposure around the 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 Risks**
+Do not provide Risks 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.
+
+**Risks 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 Risks**
+When it is omitted, the default is no supplied plausible exposure..
+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.
+
+**Risks output contract**
+Risks 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 Risks**
+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}" --risks "{risk}"
+```
+
+**Examples for Risks**
+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}" --risks "{risk}"
+vidbyte-cli --json agents suggest run --goal "{goal}" --risks "{value}"
+```
+
+**Related commands for Risks**
+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 Risks**
+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 Risks**
+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/rounds.md

@@ -0,0 +1,5 @@
+The round limit bounds how many critique-and-revision cycles may improve the candidate pool. It accepts one through eight rounds, while two rounds usually balance refinement against latency and model usage.
+
+A single round suits simple goals with clear context, while eight allows difficult ideas several revision opportunities. The workflow computes this loop shape rather than asking the model when to stop, and it ends early only when a revision returns no candidates.
+
+Each round is one critic review followed by one generator revision of the whole slate. Values outside the supported range are rejected before model work begins, and token or timeout limits still stop the run first.

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

@@ -0,0 +1,5 @@
+The suggestion agent develops concrete next actions for one meaningful goal. It returns only ideas that can be explained, evaluated, and handed to another agent.
+
+Supplied context shapes what counts as relevant, feasible, novel, and timely. A broader internal candidate pool gives independent critique enough material to reject weak or redundant directions.
+
+The final slate may be smaller than the requested maximum when stronger ideas are exhausted. Every surviving idea includes evidence, decision context, and an execution-ready action structure.

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

@@ -0,0 +1,100 @@
+**Successes**
+Successes is the named proven pattern value that this command accepts for one suggestion workflow.
+It gives the parent agent a stable way to state a method or outcome that has worked for the caller before.
+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 Successes**
+The purpose of Successes is to make a method or outcome that has worked for the caller before 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 Successes**
+Do not provide Successes 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.
+
+**Successes 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 Successes**
+When it is omitted, the default is no supplied proven pattern..
+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.
+
+**Successes output contract**
+Successes 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 Successes**
+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}" --success "{proven pattern}"
+```
+
+**Examples for Successes**
+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}" --success "{proven pattern}"
+vidbyte-cli --json agents suggest run --goal "{goal}" --success "{value}"
+```
+
+**Related commands for Successes**
+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 Successes**
+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 Successes**
+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/timeout.md

@@ -0,0 +1,5 @@
+The workflow deadline bounds elapsed time across generation, critique, and revision. It protects callers from an open-ended suggestion cycle when model responses are slow.
+
+The deadline prevents new work after expiration but does not promise cancellation within an in-flight provider request. The last fully reviewed batch remains the safe fallback.
+
+The value must be positive whenever it is specified. A time-limited result names the stopping reason so partial completion cannot resemble ordinary success.