vidbyte-cli 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,100 @@
+**Saved Result File**
+Saved Result File is the named saved suggestion result path value that this command accepts for one suggestion workflow.
+It gives the parent agent a stable way to state a previously emitted suggestions.result JSON document for local handoff extraction.
+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 Saved Result File**
+The purpose of Saved Result File is to make a previously emitted suggestions.result JSON document for local handoff extraction 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 Saved Result File**
+Do not provide Saved Result File 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.
+
+**Saved Result File inputs**
+The value is one existing JSON path.
+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 Saved Result File**
+When it is omitted, the default is no supplied saved suggestion result path..
+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.
+
+**Saved Result File output contract**
+Saved Result File 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 Saved Result File**
+Use the command below as the smallest valid invocation shape for this value.
+Replace each brace-delimited placeholder with the caller's actual text while preserving shell quoting around spaces.
+Repeat the option when more than one independent record should be supplied.
+Combine the option with a precise goal because the field is evidence or context rather than a standalone task.
+Add category and budget options only when they answer a real selection or resource question.
+The command remains a single argv-built request and does not require a temporary configuration file.
+Keep the invocation close to the caller's actual decision so another agent can reproduce the request without guessing omitted context, quoting, or precedence.
+
+```text
+vidbyte-cli agents suggest handoff --input "{result.json}" --idea "{idea-id}"
+```
+
+**Examples for Saved Result File**
+A minimal example supplies only the required goal and leaves this optional signal absent when it has no value.
+A normal example adds one focused record that directly changes how the next action should be judged.
+An advanced example repeats the option for several independent records and combines it with a selected category.
+Piping is appropriate only for a caller that captures the emitted result document, because input itself is passed through argv.
+JSON output is the stable choice when another agent will inspect identifiers, manifests, warnings, and handoffs.
+If an example fails, preserve the same goal and correct the named input or path before changing the reasoning settings.
+
+```text
+vidbyte-cli agents suggest handoff --input "{result.json}" --idea "{idea-id}"
+vidbyte-cli --json agents suggest run --goal "{goal}" --input "{value}"
+```
+
+**Related commands for Saved Result File**
+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 Saved Result File**
+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 Saved Result File**
+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/library.py

@@ -0,0 +1,29 @@
+"""Loads caller-facing suggestion help from packaged Markdown assets.
+
+The loader keeps authored prose out of Python and leaves content standards to
+the repository lint suite, so help rendering never becomes a hidden validator.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+
+
+class SuggestionHelpLibrary:
+    """Reads one named help description at a time."""
+
+    def __init__(self) -> None:
+        self._cache: dict[str, str] = {}
+
+    def load(self, name: str) -> str:
+        if name not in self._cache:
+            source = resources.files(__package__).joinpath(f"{name}.md")
+            self._cache[name] = source.read_text(encoding="utf-8").strip()
+        return self._cache[name]
+
+    def summary(self, name: str) -> str:
+        """Return the first authored help section for a context item."""
+        return self.load(name).split("\n\n", 1)[0]
+
+
+__all__ = ["SuggestionHelpLibrary"]

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

@@ -0,0 +1,5 @@
+The message limit caps how many times critics may message the generator directly during one run. A critic that finds one problem more important than a full review can stop early and send the generator a message, which the generator reads as its next turn in place of that round's review. It accepts zero through eight messages and defaults to two, the same as the default round count, because each critic sends at most one message before it stops.
+
+Once the limit is spent, later critics run without the message tool and always return a full structured review. Zero disables critic messages entirely, so every round ends in a graded review.
+
+The limit does not cover the generator's message to the parent agent. That message ends the run with the needs_input status, so it can happen at most once and needs no separate cap. Values outside the supported range are rejected before model work begins.

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

@@ -0,0 +1,5 @@
+The per-response token limit bounds the intended size of each individual model reply. It keeps one generation or critique turn from consuming the workflow's entire budget.
+
+This threshold is not a billing guarantee because an in-flight request may finish beyond it. Smaller values favor concise artifacts, while larger values accommodate richer context and candidate detail.
+
+The limit must be positive whenever it is specified. It applies consistently to generation, critique, and revision responses.

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

@@ -0,0 +1,5 @@
+The total token limit bounds the aggregate model usage scheduled across the workflow. It covers initial generation, critique, and every permitted revision.
+
+The threshold stops new work after observed usage reaches the boundary but does not interrupt an active request. Small overruns are therefore possible and should not be interpreted as ignored policy.
+
+The limit must be positive whenever it is specified. Reaching it returns the last fully reviewed candidate batch with an explicit partial-result reason.

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

@@ -0,0 +1,100 @@
+**Mistakes and Lessons**
+Mistakes and Lessons is the named prior failure lesson value that this command accepts for one suggestion workflow.
+It gives the parent agent a stable way to state an earlier mistake together with its cause and the lesson that should survive it.
+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 Mistakes and Lessons**
+The purpose of Mistakes and Lessons is to make an earlier mistake together with its cause and the lesson that should survive it 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 Mistakes and Lessons**
+Do not provide Mistakes and Lessons 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.
+
+**Mistakes and Lessons 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 Mistakes and Lessons**
+When it is omitted, the default is no supplied prior failure lesson..
+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.
+
+**Mistakes and Lessons output contract**
+Mistakes and Lessons 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 Mistakes and Lessons**
+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}" --mistakes "{failure, cause, lesson}"
+```
+
+**Examples for Mistakes and Lessons**
+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}" --mistakes "{failure, cause, lesson}"
+vidbyte-cli --json agents suggest run --goal "{goal}" --mistakes "{value}"
+```
+
+**Related commands for Mistakes and Lessons**
+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 Mistakes and Lessons**
+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 Mistakes and Lessons**
+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/outcomes.md

@@ -0,0 +1,100 @@
+**Observed Outcomes**
+Observed Outcomes is the named observed result value that this command accepts for one suggestion workflow.
+It gives the parent agent a stable way to state what happened after earlier work, decisions, or suggestions.
+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 Observed Outcomes**
+The purpose of Observed Outcomes is to make what happened after earlier work, decisions, or suggestions 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 Observed Outcomes**
+Do not provide Observed Outcomes 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.
+
+**Observed Outcomes 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 Observed Outcomes**
+When it is omitted, the default is no supplied observed result..
+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.
+
+**Observed Outcomes output contract**
+Observed Outcomes 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 Observed Outcomes**
+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}" --outcomes "{observed result}"
+```
+
+**Examples for Observed Outcomes**
+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}" --outcomes "{observed result}"
+vidbyte-cli --json agents suggest run --goal "{goal}" --outcomes "{value}"
+```
+
+**Related commands for Observed Outcomes**
+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 Observed Outcomes**
+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 Observed Outcomes**
+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/project.md

@@ -0,0 +1,100 @@
+**Project**
+Project is the key of one local suggestion project whose stored memory this run should load as context.
+A project is a small record on this machine made of a stable key, a human title, a scope description, and an ordered history of explicit accepted and rejected suggestions.
+The key is created once with agents suggest project create and then reused by every later run and every feedback call about the same body of work.
+When this option is present, the run reads the project title and description plus every recorded reaction and adds them to the bounded context before generation starts.
+When this option is absent, the run is stateless and reads no project file at all, which keeps ordinary runs reproducible from argv alone.
+The project gives a parent agent a durable memory of what the user already liked and refused, so it no longer has to restate that history by hand on every run.
+
+**Purpose of Project**
+The purpose of Project is to let suggestions improve across runs on the same work instead of starting from nothing every time.
+A project records which directions the user explicitly accepted, which ones the user explicitly rejected, and why, when the user gave a reason.
+Loading that memory lets the generator lean toward the qualities of accepted ideas and away from directions the user already turned down.
+Rejected suggestions are also used by deterministic selection, so an idea that repeats a rejected suggestion verbatim is removed before ranking.
+The project title and description tell the generator what body of work the feedback belongs to, so reactions are interpreted inside the right scope.
+The result of a project-backed run also returns ready-to-fill feedback commands, which closes the loop between suggesting, asking the user, and remembering the answer.
+
+**When not to use Project**
+Do not pass Project for a one-off question that has no relationship to earlier or later runs on the same work.
+Omit it when the stored feedback belongs to a different scope, because reactions to another codebase or goal would mislead the generator rather than help it.
+Do not create a new project for every run just to have a key, since an empty project adds only its title and description and fragments the history the feature exists to keep.
+Do not use a project as a place to store instructions, credentials, private data, or execution authority, because its contents are read as ordinary task data.
+Use the ordinary context options instead when the signal is about this run only, such as a current constraint, a decision, or a risk.
+If the project memory might be stale or wrong, repair the feedback history first rather than asking the generator to ignore part of it.
+
+**Project inputs**
+The value is one project key made of 1 to 64 lowercase letters, numbers, hyphens, or underscores, beginning with a letter or number.
+Surrounding whitespace is trimmed before the key is checked, and a key with uppercase letters, slashes, dots, or other characters is rejected before any file is read.
+The key must already exist in the local project catalog, because a run never creates a project implicitly.
+Only one project may be supplied per run, so a run's memory always comes from exactly one scope.
+The project title and description are loaded as one context kind named project, while accepted and rejected reactions are loaded as the accepted_feedback and rejected_feedback kinds.
+Each reaction becomes its own context item, with the user's reason on the line after the suggestion when a reason was recorded.
+Project items are subject to the same per-item and total context bounds as caller-supplied flags, so a very long history is truncated or omitted visibly rather than silently.
+
+**Defaults and precedence for Project**
+The default is no project, which means a stateless run that reads no project catalog and no memory file.
+Nothing selects a project implicitly, so neither an environment variable, a configuration value, nor the current directory can turn project memory on.
+When a project is supplied, its items are appended after every caller-supplied context flag, so caller references keep their numbering and project items follow them.
+Caller context and project memory are both kept, and neither overrides the other, so a caller can add a current constraint that narrows what past feedback suggests.
+Other settings such as count, categories, rounds, and provider stay independent and are not stored in the project.
+The feedback history is read fresh on every run, so a reaction recorded a moment ago is already part of the next run's context.
+The result manifest records each project item with its reference, kind, size, and inclusion status, exactly like any other context item.
+
+**Project output contract**
+A project-backed result carries the project key in its project_key field so a downstream agent can tell which memory shaped the slate.
+The result also carries a feedback_capture object with an instruction plus one accept command and one reject command already filled in with this project key.
+Human output prints the same accept and reject commands after the ranked ideas, so a person or agent can record the user's reaction without reading help again.
+A stateless run returns a null project_key and a null feedback_capture, which is how a caller can confirm that no project file was read.
+Dry-run output still resolves the project and lists its items in the manifest, which makes dry-run the safe way to inspect what memory a run would load.
+The project option never grants execution authority, never records feedback by itself, and never changes the project files it reads.
+
+**How to use Project**
+Create the project once with a key, a short title, and a description of its scope.
+Pass that key with this option on every suggestion run that concerns the same work.
+After showing the ideas to the user, record the user's clear acceptance or rejection with the feedback command printed in the result.
+Include the user's reason whenever the user gives one, because the reason tells the next run which quality mattered rather than only which idea.
+Use project list to recover a key when a new session does not know which projects already exist.
+Run with dry-run first when you want to see exactly which project items would enter the context before any model is called.
+
+```text
+vidbyte-cli agents suggest run --project "{project-key}" --goal "{goal}"
+```
+
+**Examples for Project**
+A minimal example runs one suggestion pass with the memory of an existing project and nothing else beyond the goal.
+A normal example adds a current constraint so the run respects both the stored history and a fact that is only true today.
+An inspection example uses dry-run with JSON output to list the project items in the manifest without calling a provider.
+A full loop creates the project, runs with it, records the user's rejection with a reason, and runs again so the next slate avoids that direction.
+JSON output is the stable choice when another agent will read project_key, feedback_capture, and the manifest programmatically.
+If an example fails with a missing project, list the catalog and correct the key before changing any other option.
+
+```text
+vidbyte-cli agents suggest run --project "{project-key}" --goal "{goal}"
+vidbyte-cli agents suggest run --project "{project-key}" --goal "{goal}" --constraint "{constraint}"
+vidbyte-cli --json agents suggest run --project "{project-key}" --goal "{goal}" --dry-run
+vidbyte-cli agents suggest feedback reject --project "{project-key}" --suggestion "{suggestion}" --reason "{reason}"
+```
+
+**Related commands for Project**
+Use agents suggest project create to register a new key with its title and description before the first project-backed run.
+Use agents suggest project list to see every existing key, title, and description without opening any feedback file.
+Use agents suggest feedback accept to record a suggestion the user clearly wanted, together with the reason when one was given.
+Use agents suggest feedback reject to record a suggestion the user clearly refused, so later runs stop proposing that direction.
+Use agents suggest handoff after a project-backed run exactly as after a stateless one, since the saved result keeps the same shape.
+These commands share one local project store, but none of them calls a model except the run itself.
+
+**Failure modes for Project**
+A key that does not match the allowed character pattern fails as an invalid project before any file is read.
+A well-formed key that is not in the catalog fails as a missing project, and nothing is created in its place.
+A catalog or memory file that is not valid JSON, does not match its schema, or belongs to a different key fails as unreadable project state.
+A memory file that the catalog links to but that is missing from disk also fails as unreadable state rather than being treated as an empty history.
+None of these failures calls a model or changes any project file, so the invocation can be corrected and retried safely.
+Recover by listing projects to confirm the key, then repair or remove only the named invalid file if the state itself is broken.
+
+**Authentication and permissions for Project**
+Reading project memory requires no Vidbyte login, API key, or provider credential.
+Project files live only in the platform-native Vidbyte data directory on this machine and are never uploaded by this option.
+The run reads exactly the catalog and the one memory file linked to the supplied key and scans nothing else.
+A model-backed run still needs its configured provider, while a dry run resolves the project without any provider at all.
+Permission errors on the data directory surface as unreadable project state and are repaired at the filesystem, not by weakening the option.
+Project contents are passed to agents as task data only and never grant the generator or critic any permission to act.

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

@@ -0,0 +1,7 @@
+Project create registers one new local suggestion project under a stable key, with a human-readable title and a plain-language description of its scope. The key becomes the selector every later command uses: feedback accept and feedback reject append reactions to it, and agents suggest run with the project option loads its memory into a run.
+
+Creation writes an empty feedback memory file first and then publishes the project in the catalog, so a listed project always has a readable memory file. If the catalog cannot be written, the new memory file is removed again so the same key can be retried. A key that already exists, or whose memory file is already on disk, is refused instead of being overwritten, which keeps an existing project's feedback history safe.
+
+Choose one project per body of work that suggestions will be about, such as a repository, a product area, or a long-running goal. Put durable scope in the description, because it frames every accepted and rejected reaction on every later run, and keep run-specific facts in the run's own context options.
+
+The command is local and deterministic. It needs no credentials, makes no model call, and sends nothing to Vidbyte. JSON output returns the created record, including the key and its linked memory file, and human output prints one confirmation line.

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

@@ -0,0 +1,98 @@
+**Project description**
+Project description is the plain-language statement of scope stored with a new local suggestion project.
+It tells every later project-backed run what body of work the project covers, what it is trying to achieve, and where its boundaries lie.
+The description is loaded into the run's context next to the title before any accepted or rejected feedback is read.
+That placement matters because a reaction such as rejecting a database suggestion only makes sense once the generator knows what system it was about.
+The description may be several sentences long and should read as a briefing a new teammate could act on.
+It is stored verbatim apart from trimming surrounding whitespace, and it is never rewritten or summarized by the CLI.
+
+**Purpose of Project description**
+The purpose of Project description is to give recorded feedback a frame, so the generator can generalize from past reactions without overgeneralizing.
+A clear scope lets the generator tell whether a new idea falls inside the project or drifts into neighbouring work the user never discussed.
+It also records durable facts that would otherwise have to be repeated as context flags on every run, such as the product's audience or the repository's role.
+For a parent agent that lost its transcript, the description is often the fastest way to confirm it picked the right project from the list.
+A description that names what the project is not about is especially useful, because it prevents suggestions from wandering into excluded areas.
+Good descriptions make accepted and rejected feedback more informative per record, which means fewer reactions are needed before suggestions improve.
+
+**When not to use Project description**
+Do not put run-specific facts in the description, because it is loaded on every run and stale facts will keep influencing suggestions.
+Use the constraint, decision, or risk options on a run for information that is true only for that run.
+Do not write instructions to the model in the description, since it is loaded as data and never treated as a directive.
+Do not paste long documents, transcripts, or file contents, because the description is capped and long text crowds out more useful context.
+Keep credentials, personal data, and confidential customer details out of the description because it is sent to the provider on real runs.
+If the scope is still unsettled, write what is known today rather than guessing at boundaries that may prove wrong.
+
+**Project description inputs**
+The value is one nonempty string of at most 4000 characters after surrounding whitespace is trimmed.
+Multiple sentences, line breaks inside a quoted argument, and ordinary punctuation are all accepted.
+A value made only of whitespace is rejected, because an empty description would leave feedback without a frame.
+The option is required, so creation refuses to run without a description.
+Validation happens in the command's input dataclass together with the key and title, before the catalog is read.
+The description is stored as plain text and is never parsed, templated, or split into separate records.
+Because the description is loaded on every project-backed run, its length also counts against that run's shared context budget.
+
+**Defaults and precedence for Project description**
+There is no default description, because only the caller can state the scope of the work.
+The value comes only from this option and is never read from an environment variable, a configuration file, or a repository file.
+Trimming surrounding whitespace is the only normalization applied, so the rest of the wording is preserved exactly.
+The description is fixed at creation in this version, and there is no command that edits it afterwards.
+On a project-backed run, caller-supplied context flags come first and the description follows them as part of the project item.
+Neither source overrides the other, so a run-level constraint can narrow what the description implies for that single run.
+
+**Project description output contract**
+On success the created document's data includes the description exactly as stored after trimming.
+Project list prints the description under each key in human output and includes it as a field in JSON output.
+A project-backed run includes the description as a context line labelled Project description within the project context kind.
+The result manifest records that item's size, hash, and inclusion status, so truncation or omission is visible rather than silent.
+The description never appears in file names and never changes where project memory is stored.
+Errors about the description are reported as an invalid project without echoing the rejected value.
+
+**How to use Project description**
+Write two to five sentences naming the work, its goal, its audience, and anything it deliberately excludes.
+Pass it in quotes together with the key and title in one project create call.
+Prefer durable facts that will still be true in a month over the details of the current task.
+Mention the boundaries that past or expected feedback depends on, such as a rule against adding new infrastructure.
+Keep the description well under its limit so it never competes for space with the feedback it frames.
+Read it back with project list before relying on it, since it cannot be edited after creation in this version.
+
+```text
+vidbyte-cli agents suggest project create --key "{project-key}" --title "{title}" --description "{description}"
+```
+
+**Examples for Project description**
+A repository example describes a command-line client, its users, and the rule that research runs on the backend rather than locally.
+A goal example describes a quarter-long onboarding effort, the metric it targets, and the teams it must not disrupt.
+A component example describes one service, the interfaces it owns, and the neighbouring services that are out of scope.
+A weak example is a single phrase that repeats the title, which gives feedback almost no frame to be interpreted in.
+JSON output returns the stored description in the created document, which lets an agent verify the exact wording.
+If creation fails because of the description, shorten or fill in the value and retry with the same key and title.
+
+```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 description**
+Use agents suggest project list to read every stored description next to its key and title.
+Use agents suggest run with the project option to load this description into a run as part of the project context item.
+Use run-level context options such as constraint and decision for facts that apply only to one run.
+Use agents suggest feedback accept and reject to add reactions that the description will frame on later runs.
+Use dry-run on a project-backed run to see the description's manifest entry without calling a provider.
+None of these commands edits the description, which is set once by project create.
+
+**Failure modes for Project description**
+A missing description fails as a usage error before any file is read.
+A description that is empty after trimming fails as an invalid project and nothing is written.
+A description longer than 4000 characters fails as an invalid project with the bound named in the error.
+A valid description never fails on its content, because its wording is not interpreted by the CLI.
+Creation can still fail for unrelated reasons, such as an existing key or an unwritable data directory.
+Recover from a description failure by shortening or supplying the value and repeating the same create call.
+A failed call writes nothing, so repeating it after a correction cannot leave a half-created project behind.
+
+**Authentication and permissions for Project description**
+Supplying a description requires no Vidbyte login, API key, or provider credential.
+The description 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 description locally and send nothing anywhere.
+The description grants no permission to any agent and cannot widen what a generator or critic may do.
+Keep sensitive material out of the description because it is shared with the provider whenever the project is used in a real run.

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

@@ -0,0 +1,7 @@
+Suggestion projects give the suggestion agent a durable local memory for one body of work. A project is a stable key, a human title, a scope description, and an ordered history of suggestions the user explicitly accepted or rejected, kept on this machine in the platform-native Vidbyte data directory.
+
+The project lifecycle has four steps. Create a project once with project create, pass its key to agents suggest run with the project option so the run loads the title, description, and every recorded reaction, record the user's clear reactions with feedback accept or feedback reject, and run again so the next slate builds on what the user liked and avoids what the user refused. Use project list at any point to recover an existing key instead of creating a duplicate.
+
+The catalog of projects lives in one projects.json file, and each project links to its own memory file under the projects directory beside it. Every write replaces a whole document atomically, so an interrupted command leaves the previous valid state in place rather than a truncated file.
+
+Project commands never call a model and need no Vidbyte login, API key, or provider. Only a suggestion run that passes a project key sends the project's contents to a provider, and only as task data that grants no permission to act.