vidbyte-cli 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,100 @@
+**Decision Context**
+Decision Context is the named open or constrained choice value that this command accepts for one suggestion workflow.
+It gives the parent agent a stable way to state a decision that is pending, already bounded, or likely to shape the next move.
+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 Decision Context**
+The purpose of Decision Context is to make a decision that is pending, already bounded, or likely to shape the next move 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 Decision Context**
+Do not provide Decision Context 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.
+
+**Decision Context 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 Decision Context**
+When it is omitted, the default is no supplied open or constrained choice..
+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.
+
+**Decision Context output contract**
+Decision Context 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 Decision Context**
+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}" --decision "{decision context}"
+```
+
+**Examples for Decision Context**
+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}" --decision "{decision context}"
+vidbyte-cli --json agents suggest run --goal "{goal}" --decision "{value}"
+```
+
+**Related commands for Decision Context**
+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 Decision Context**
+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 Decision Context**
+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/dry_run.md

@@ -0,0 +1,5 @@
+A dry run validates and resolves the complete request without invoking a model. It exposes settings, manifest entries, omissions, and warnings before reasoning incurs cost or latency.
+
+File bodies stay out of the result by default while source identity and inclusion status remain inspectable. This makes large or sensitive context sets easier to audit safely.
+
+No provider credentials or token usage are required for this validation path. The result contains no ideas and clearly identifies dry-run completion as its stopping reason.

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

@@ -0,0 +1,5 @@
+Extra compute runs one independent suggestion agent for each selected category and combines their structured results before critique. Each category receives the same goal and caller context, but its own focused category window, so the run can explore more distinct directions.
+
+The default is off because one shared window is usually enough and uses fewer model turns. Enable it when breadth matters more than latency or when several categories deserve separate attention. The combined pool is still bounded by the requested count and the workflow's total token and time limits.
+
+This setting changes the generation topology, not the meaning of a category or the final schema. Every per-category result is labeled before combination, and the independent critic still reviews the combined candidates. A provider failure stops the provider-backed run with its typed error so the caller never mistakes a partial pool for a complete result.

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

@@ -0,0 +1,7 @@
+Feedback accept records one suggestion that the user explicitly accepted for an existing local project. The suggestion text and the user's optional reason are appended to that project's memory, after every earlier record, so later project-backed runs can recognize which directions and qualities the user found useful.
+
+Call it only when the acceptance is clear, such as the user saying they want to do the idea or choosing it over the alternatives. Do not infer acceptance from silence, from the user moving on, or from the user implementing unrelated or merely similar work. When the user explains why they liked the idea, pass that explanation as the reason, because it lets the generator look for the same property in future ideas.
+
+The project must already exist, and an unknown or malformed key fails before any file is changed. The memory file is replaced atomically, so a failed write leaves the previous history intact and reports no success.
+
+The command is local and deterministic. It needs no credentials, makes no model call, and does not execute or approve the suggestion. JSON output returns the project key and the stored record, and human output prints one confirmation line.

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

@@ -0,0 +1,7 @@
+Suggestion feedback records the user's explicit reaction to a suggestion in one local project's memory. The accept verb records a suggestion the user clearly wanted, and the reject verb records a suggestion the user clearly refused; both store the suggestion text, the user's optional reason, and a UTC timestamp.
+
+Recorded feedback is what makes project-backed runs improve over time. The next agents suggest run that passes the same project key loads every accepted and rejected record as context, so the generator can prefer the qualities of accepted ideas, and ideas that repeat a rejected suggestion word for word are removed before ranking.
+
+Record feedback only when the user's reaction is explicit. Silence, a change of topic, partial interest, or the user implementing something similar is never acceptance or rejection, and a reason should carry the user's own explanation rather than one the calling agent inferred. A project-backed run returns both feedback commands with the project key already filled in, which is the safest template to use.
+
+Feedback commands are local and deterministic. They need no credentials, make no model call, and never execute, approve, or schedule the suggestion they record. Each call appends one record after every earlier one and never edits or removes history.

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

@@ -0,0 +1,100 @@
+**Feedback project**
+Feedback project is the key of the existing local project whose memory should receive this accepted or rejected reaction.
+It selects exactly one project catalog entry and, through it, exactly one per-project memory file to append to.
+The project must have been created earlier with agents suggest project create, because feedback never creates a project on its own.
+Every reaction recorded under the same key joins one ordered history that later project-backed runs load as context.
+The value is usually copied from the feedback commands a project-backed run returns, which already contain the right key.
+Getting the key right matters more than any other field, because a reaction filed under the wrong project teaches the wrong scope.
+
+**Purpose of Feedback project**
+The purpose of Feedback project is to attach the user's reaction to the body of work it was actually about.
+Suggestions are only comparable within one scope, so a rejection recorded against one repository must not steer suggestions for another.
+The key keeps each project's memory separate even when several projects exist on the same machine.
+It also lets a parent agent record feedback in a later session than the run that produced the suggestion, as long as it still knows the key.
+A single stable key per project is what turns scattered reactions into a history the generator can learn from.
+That history is read in full on the next project-backed run, so the recorded reaction takes effect immediately.
+
+**When not to use Feedback project**
+Do not guess a key when the right project is unclear, because a misfiled reaction silently distorts that project's future suggestions.
+Do not record feedback under a project whose scope does not match the suggestion, even if it is the only project that exists.
+Do not create a new project just to record one reaction, since that reaction would then never be seen by runs on the real project.
+Avoid reusing a key across unrelated work merely because it is short or familiar.
+If the suggestion came from a stateless run, decide which project it belongs to before recording anything.
+When no project fits, create one with a clear scope first and record the feedback there.
+
+**Feedback project inputs**
+The value is one project key of 1 to 64 lowercase letters, numbers, hyphens, or underscores, beginning with a letter or number.
+Whitespace around the key is trimmed before validation, and any other character makes the key invalid.
+The key must already be present in the local project catalog.
+The option is required, so the command refuses to run without it.
+A malformed key fails before the catalog is opened, and an unknown key fails before the memory file is touched.
+Only one project may receive a given reaction, so recording the same reaction for two projects takes two calls.
+
+**Defaults and precedence for Feedback project**
+There is no default project, because recording feedback against an assumed scope would be worse than recording nothing.
+The key comes only from this option and is never read from an environment variable, a configuration value, or the current directory.
+The key is not created implicitly when it is missing from the catalog.
+The trimmed key is the canonical form and must match the stored key exactly.
+A project-backed run's result supplies the key already filled into its feedback commands, which is the most reliable source for it.
+Other feedback options do not influence which project is selected.
+Passing the key explicitly on every call is what keeps a reaction from ever landing in a project the caller did not intend.
+
+**Feedback project output contract**
+On success the command returns a suggestions.feedback.recorded document whose data names the project key and the stored feedback record.
+Human output prints one confirmation line naming the reaction type and the project key.
+The reaction is appended to the end of that project's memory file, after every earlier record.
+Nothing in the project catalog changes when feedback is recorded, because feedback lives only in the linked memory file.
+The memory file is replaced atomically, so a reader sees either the previous history or the new one and never a partial file.
+Errors go to the error channel as typed envelopes, and stdout stays empty when recording fails.
+
+**How to use Feedback project**
+Take the key from the feedback commands printed by the project-backed run whose suggestion the user reacted to.
+When those commands are not available, list the projects and pick the key whose title and description match the suggestion's scope.
+Pass the key with the suggestion text and, when available, the user's reason.
+Record the reaction as soon as the user states it clearly, so the next run already benefits from it.
+Keep using the same key for every later reaction about the same work.
+If the command reports an unknown project, correct the key rather than creating a new project with a similar name.
+
+```text
+vidbyte-cli agents suggest feedback accept --project "{project-key}" --suggestion "{suggestion}"
+```
+
+**Examples for Feedback project**
+A typical example records the user's acceptance of one suggestion under the project the run was made for.
+A second example records a rejection with a reason under the same key so the next run avoids that direction.
+A recovery example lists the projects first because the session no longer remembers which key was used.
+A mistaken example passes a key with capital letters, which fails immediately and can be retyped in lowercase.
+JSON output returns the key and the stored record, which lets another agent confirm where the reaction landed.
+If a call fails because the project is missing, create or locate the project and repeat the same call.
+
+```text
+vidbyte-cli agents suggest feedback accept --project "{project-key}" --suggestion "{suggestion}"
+vidbyte-cli agents suggest feedback reject --project "{project-key}" --suggestion "{suggestion}" --reason "{reason}"
+vidbyte-cli --json agents suggest project list
+```
+
+**Related commands for Feedback project**
+Use agents suggest project list to find an existing key and confirm its scope.
+Use agents suggest project create when no existing project matches the work the suggestion was about.
+Use agents suggest run with the project option to load this project's accumulated feedback into the next run.
+Use the sibling feedback verb when the user's reaction was the opposite disposition.
+The same key connects all of these commands, and nothing else links a reaction to a project.
+None of these commands calls a model except the suggestion run itself.
+Reading the project list before a first feedback call in a new session is the cheapest way to avoid filing a reaction under the wrong key.
+
+**Failure modes for Feedback project**
+A missing key fails as a usage error before anything is read.
+A key with invalid characters fails as an invalid project before the catalog is opened.
+A well-formed key absent from the catalog fails as a missing project, and no file is created or changed.
+A catalog or memory file that is malformed, missing, or belongs to another key fails as unreadable project state.
+A filesystem refusal while replacing the memory file fails as a write failure, and the previous history stays intact.
+Recover by correcting the key, creating the project, or repairing the named file, then repeat the same call.
+
+**Authentication and permissions for Feedback project**
+Recording feedback requires no Vidbyte login, API key, or model provider.
+The command reads the local catalog and replaces one local memory file inside the platform-native Vidbyte data directory.
+Nothing is sent to Vidbyte or to any provider when feedback is recorded.
+The command needs permission to replace files in that data directory and reports a write failure when the filesystem refuses.
+Knowing a project key grants no additional permission, since every project is local to this machine and user.
+Repair permission problems at the data directory rather than by recording feedback under a different project.
+Because the memory stays local, removing the project's files is the only way to erase its recorded feedback.

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

@@ -0,0 +1,98 @@
+**Feedback reason**
+Feedback reason is the user's own explanation of why they accepted or rejected the suggestion.
+It is optional, and it is stored with the suggestion text in the same feedback record.
+On later project-backed runs the reason appears on the line after the suggestion, so the generator learns what quality drove the reaction.
+A reason often matters more than the reaction itself, because it tells the generator which neighbouring ideas would be welcome or unwelcome too.
+The value should carry the user's meaning, not a rationale the calling agent invented afterwards.
+Leaving it out is correct whenever the user gave a clear reaction without saying why.
+
+**Purpose of Feedback reason**
+The purpose of Feedback reason is to let one reaction generalize correctly to future ideas the user has not seen yet.
+Without a reason, a rejected suggestion only tells the generator to avoid that exact direction.
+With a reason such as too much new infrastructure, it can also avoid other ideas that share the same drawback.
+For accepted suggestions, a reason such as small enough to ship this week tells the generator which property to look for again.
+Reasons also make the project memory auditable, since a person can later see why each decision was made.
+Storing the reason separately from the suggestion text keeps the suggestion matchable while still preserving the explanation.
+
+**When not to use Feedback reason**
+Do not invent a reason when the user did not give one, because a fabricated reason steers every later run in a direction the user never chose.
+Do not summarize a long conversation into a reason that the user would not recognize as their own view.
+Do not use the reason to give the generator instructions, since it is loaded as data and never as a directive.
+Avoid restating the suggestion itself as the reason, which adds length without adding meaning.
+Keep credentials, private data, and confidential details out of the reason, because it is sent to the provider on real runs.
+If the user's explanation covers several suggestions, record it with each one separately rather than once for all of them.
+
+**Feedback reason inputs**
+The value is one optional string of at most 8192 characters.
+When supplied, it is stored exactly as passed, including surrounding whitespace.
+When omitted, the stored reason is null rather than an empty string, so absence remains distinguishable from a blank value.
+Quotes, punctuation, and line breaks inside a quoted shell argument are accepted.
+Validation happens in the feedback input dataclass before the project catalog is opened.
+The reason is never parsed or classified, so any wording the user chose is preserved.
+Because the reason is kept apart from the suggestion text, its wording never affects which later ideas are suppressed as verbatim repeats of a rejection.
+
+**Defaults and precedence for Feedback reason**
+The default is no reason, which records the reaction on its own.
+The value comes only from this option and is never read from a result file, an environment variable, or configuration.
+The reason never changes the reaction type, which is fixed by whether the accept or reject verb was called.
+A later reaction's reason does not replace an earlier one, because each record keeps its own reason.
+When several records about similar suggestions carry different reasons, all of them are loaded and weighed together on the next run.
+The reason is loaded only on runs that pass this project's key, and stateless runs never see it.
+
+**Feedback reason output contract**
+On success the returned document's feedback record includes the reason, or null when it was omitted.
+On later project-backed runs the reason appears in the same context item as its suggestion, on the line after the suggestion text.
+Rejected-suggestion suppression uses only the suggestion text, so a reason never causes an unrelated idea to be filtered.
+Human output prints only a confirmation line, while JSON output includes the full stored record.
+The result manifest of a later run counts the reason inside its feedback item's size and inclusion status.
+Errors about the reason are reported as invalid feedback without echoing the rejected value.
+
+**How to use Feedback reason**
+Pass the user's explanation in quotes on the same accept or reject call as the suggestion.
+Keep the user's words where possible, trimming only filler that does not change the meaning.
+Prefer a reason that names a property, such as cost, risk, timing, or scope, over one that only expresses a mood.
+Omit the option entirely when the user did not explain the reaction.
+Record one reason per suggestion so each reaction stays independently interpretable.
+Check the stored record in JSON output when another agent will depend on the exact wording.
+A short reason in the user's own words is more useful to the next run than a long paraphrase written by the calling agent.
+
+```text
+vidbyte-cli agents suggest feedback reject --project "{project-key}" --suggestion "{suggestion}" --reason "{reason}"
+```
+
+**Examples for Feedback reason**
+A rejection example stores a reason saying the idea adds backend infrastructure the project deliberately avoids.
+An acceptance example stores a reason saying the idea can be finished this week without new dependencies.
+A minimal example records a clear rejection with no reason, because the user simply said no.
+A mistaken example stores a reason the calling agent guessed, which should instead have been left out.
+JSON output shows the stored reason or null, which confirms whether a reason reached the project memory.
+If a call fails because the reason is too long, shorten it to the user's essential point and repeat the call.
+
+```text
+vidbyte-cli agents suggest feedback reject --project "{project-key}" --suggestion "{suggestion}" --reason "{reason}"
+vidbyte-cli agents suggest feedback accept --project "{project-key}" --suggestion "{suggestion}" --reason "{reason}"
+```
+
+**Related commands for Feedback reason**
+Use the suggestion option on the same command to store which direction the reason is about.
+Use agents suggest run with the project option to have later runs read both the suggestion and its reason.
+Use run-level context options instead when the explanation is a fact about the current run rather than a reaction to a suggestion.
+Use agents suggest project list to confirm the right project before recording a reason under it.
+Use the opposite feedback verb when the user's reason reveals the reaction was actually the other disposition.
+None of these commands rewrites a stored reason, so a wrong reason is corrected by recording a new reaction.
+
+**Failure modes for Feedback reason**
+A reason longer than 8192 characters fails as invalid feedback and nothing is written.
+A valid reason never fails on its wording, because the CLI does not interpret it.
+The call can still fail when the suggestion text is invalid, the project is unknown, or its memory file is unreadable.
+A filesystem refusal while replacing the memory file fails as a write failure, and earlier records stay intact.
+Omitting the reason is never an error and always records the reaction with a null reason.
+Recover from a reason failure by shortening the text to the user's essential point and repeating the same call.
+
+**Authentication and permissions for Feedback reason**
+Recording a reason requires no Vidbyte login, API key, or model provider.
+The reason is written only to the project's local memory file inside the platform-native Vidbyte data directory.
+It leaves the machine only when a later model-backed run with this project sends its context to the configured provider.
+A reason grants no permission to any agent and cannot authorize or forbid any action on its own.
+The command needs permission to replace the memory file and reports a write failure when the filesystem refuses.
+Keep secrets and private data out of the reason because it is shared with the provider on real project-backed runs.

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

@@ -0,0 +1,7 @@
+Feedback reject records one suggestion that the user explicitly rejected for an existing local project. The suggestion text and the user's optional reason are appended to that project's memory, after every earlier record, so later project-backed runs stop proposing the same unwanted direction.
+
+Rejected feedback has two effects on the next run with this project. The generator reads the rejection and its reason as context and steers away from ideas with the same drawback, and deterministic selection removes any idea whose title, summary, or actions repeat the rejected suggestion text word for word.
+
+Call it only when the rejection is clear, such as the user saying no or explaining why the idea does not fit. Do not infer rejection from silence, a change of topic, or the user simply not acting on the idea yet. A reason is especially valuable here, because it lets one rejection rule out a whole family of similar ideas rather than one wording.
+
+The project must already exist, and an unknown or malformed key fails before any file is changed. The command is local and deterministic, needs no credentials, makes no model call, and never removes earlier feedback. JSON output returns the project key and the stored record, and human output prints one confirmation line.

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

@@ -0,0 +1,101 @@
+**Feedback suggestion**
+Feedback suggestion is the text of the suggestion the user explicitly accepted or rejected.
+It is stored verbatim in the project's memory and becomes one context item on every later run that loads the project.
+The text should identify the direction clearly enough that a future generator can recognize it without the original result document.
+Usually that means the suggestion's title, optionally followed by the short summary or first action that made the direction concrete.
+The value is preference history, not a task, so recording it never executes, schedules, or approves any work.
+For rejected feedback the verbatim text is also used to remove later ideas that repeat it word for word.
+
+**Purpose of Feedback suggestion**
+The purpose of Feedback suggestion is to preserve which direction the user reacted to, in words the next run can match against.
+Accepted suggestions show the generator which qualities of an idea were useful, so it can propose more ideas with those qualities.
+Rejected suggestions show the generator which directions to stop proposing, and the exact text lets deterministic selection filter verbatim repeats.
+Storing the text rather than an idea identifier keeps the memory meaningful after the original result file is gone.
+A clear record also lets a person audit the project memory later and understand each decision without reconstructing old runs.
+The more precisely the text names the direction, the less the generator has to guess about what the user meant.
+
+**When not to use Feedback suggestion**
+Do not record a suggestion the user has not clearly reacted to, because silence, a topic change, or partial interest is not feedback.
+Do not record an idea as accepted merely because the user later implemented something similar, unless the user said so.
+Do not paraphrase the suggestion into a different claim, since that records a reaction the user never gave.
+Avoid pasting an entire result document, because a long record dilutes the signal and may be truncated in later runs.
+Do not use this field to leave instructions for the generator, since it is loaded as data and never as a directive.
+If the user reacted to several suggestions, record each one in its own call rather than joining them into one text.
+
+**Feedback suggestion inputs**
+The value is one string of at most 8192 characters that is not empty or whitespace only.
+Surrounding whitespace is preserved exactly as supplied, so the stored text matches what the caller passed.
+Quotes, punctuation, and line breaks inside a quoted shell argument are all accepted.
+The option is required, so the command refuses to run without it.
+Validation happens in the feedback input dataclass before the project catalog is opened.
+The text is not compared against earlier records, so recording the same suggestion twice keeps both entries as history.
+Because the text is stored verbatim, the caller controls exactly what later runs will see and what rejected suggestions will match.
+
+**Defaults and precedence for Feedback suggestion**
+There is no default suggestion text, because only the caller knows which direction the user reacted to.
+The value comes only from this option and is never read from a saved result file, an environment variable, or configuration.
+The reaction type comes from the command name, accept or reject, and never from anything inside this text.
+Records are appended in call order, so the history reflects the order in which reactions were recorded.
+An earlier record is never edited or removed by a later one, even when the later record has the opposite disposition.
+When accepted and rejected records about the same direction coexist, both are loaded and the generator weighs them together.
+
+**Feedback suggestion output contract**
+On success the returned document's feedback record includes the suggestion text exactly as stored.
+The record also includes the reaction type, the optional reason, and a UTC creation timestamp.
+On later project-backed runs the text appears in context as Accepted suggestion or Rejected suggestion followed by the stored words.
+When a reason was recorded, it appears on the next line after the suggestion text in that same context item.
+Human output prints only a confirmation line, while JSON output includes the full stored record.
+Errors about the text are reported as invalid feedback without echoing the rejected value.
+The stored record is never altered by later calls, so the returned document remains an accurate description of what was saved.
+
+**How to use Feedback suggestion**
+Copy the suggestion's title from the result the user reacted to, and add its summary when the title alone is ambiguous.
+Pass it in quotes with the project key using the accept or reject verb that matches the user's reaction.
+Record one suggestion per call so each reaction keeps its own reason and timestamp.
+Keep the wording close to the original so rejected text can match a repeated idea exactly.
+Add the user's reason with the reason option whenever the user explained the reaction.
+Record the reaction promptly so the next run in the same session already reflects it.
+Short, specific wording is easier for the next run to recognize than a long paragraph copied from the result.
+
+```text
+vidbyte-cli agents suggest feedback reject --project "{project-key}" --suggestion "{suggestion}"
+```
+
+**Examples for Feedback suggestion**
+An acceptance example records a suggested caching layer by its title because the user said they want to build it next.
+A rejection example records a suggestion to adopt a new database because the user said the project must avoid new infrastructure.
+A detailed example records a title followed by its first action because two earlier ideas shared similar titles.
+A mistaken example records a whole result document, which is valid but wastes context and may be truncated later.
+JSON output shows the stored record, which confirms the exact text that later runs will see.
+If a call fails as invalid feedback, supply nonempty text within the length bound and repeat the call.
+
+```text
+vidbyte-cli agents suggest feedback accept --project "{project-key}" --suggestion "{suggestion}"
+vidbyte-cli agents suggest feedback reject --project "{project-key}" --suggestion "{suggestion}" --reason "{reason}"
+```
+
+**Related commands for Feedback suggestion**
+Use agents suggest run with the project option to generate the suggestions whose text you record here.
+Use the feedback commands printed in a project-backed result as a template with the key already filled in.
+Use agents suggest handoff when the user accepted an idea and another agent needs its full action packet.
+Use the reason option on this same command to store why the user reacted as they did.
+Use agents suggest project list to confirm which project a suggestion belongs to before recording it.
+None of these commands executes the suggestion, and recording feedback never starts work.
+Keeping these steps separate means the caller always decides explicitly when a reaction is recorded.
+
+**Failure modes for Feedback suggestion**
+A missing suggestion option fails as a usage error before anything is read.
+Text that is empty or whitespace only fails as invalid feedback and nothing is written.
+Text longer than 8192 characters fails as invalid feedback with the bound named in the error.
+A valid text can still fail to be recorded when the project is unknown or its memory file is unreadable.
+A filesystem refusal while replacing the memory file fails as a write failure, and earlier records stay intact.
+Recover from a text failure by shortening or supplying the suggestion, then repeat the same call.
+No failure ever records a partial reaction, so a retry cannot create a duplicate of a record that was never saved.
+
+**Authentication and permissions for Feedback suggestion**
+Recording suggestion text requires no Vidbyte login, API key, or model provider.
+The text is written only to the project's local memory file inside the platform-native Vidbyte data directory.
+It leaves the machine only when a later model-backed run with this project sends its context to the configured provider.
+Recording feedback grants no permission to any agent and cannot authorize the suggestion it names.
+The command needs permission to replace the memory file and reports a write failure when the filesystem refuses.
+Keep secrets and private data out of the text because it is shared with the provider on real project-backed runs.

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

@@ -0,0 +1,100 @@
+**Supporting Files**
+Supporting Files is the named caller-selected file value that this command accepts for one suggestion workflow.
+It gives the parent agent a stable way to state a text, Markdown, or documented JSON file whose bounded content may inform the run.
+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 Supporting Files**
+The purpose of Supporting Files is to make a text, Markdown, or documented JSON file whose bounded content may inform the run 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 Supporting Files**
+Do not provide Supporting Files 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.
+
+**Supporting Files inputs**
+The value is one existing .txt, .md, or .json path 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 Supporting Files**
+When it is omitted, the default is no supplied caller-selected file..
+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.
+
+**Supporting Files output contract**
+Supporting Files 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 Supporting Files**
+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}" --files "{path/to/context.md}"
+```
+
+**Examples for Supporting Files**
+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}" --files "{path/to/context.md}"
+vidbyte-cli --json agents suggest run --goal "{goal}" --files "{value}"
+```
+
+**Related commands for Supporting Files**
+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 Supporting Files**
+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 Supporting Files**
+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.