chore(release): promote beta to stable

.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "vidxp",
+  "interface": {
+    "displayName": "VidXP"
+  },
+  "plugins": [
+    {
+      "name": "vidxp",
+      "source": {
+        "source": "local",
+        "path": "./plugins/vidxp"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

.agents/skills/maintain-docs/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: maintain-docs
+description: Maintain and review VidXP repository documentation, including README.md, INSTALLATION_GUIDE.md, docs/**/*.md, release copy, and contributor guides. Use when documentation or product behavior, CLI, HTTP, MCP, Desktop, deployment, releases, contributor workflows, architecture, research, or integrations change. Route information to the correct human or agent audience, verify claims against repository evidence, preserve nonredundant details, improve prose and flow, and report validation and warnings. Do not use for product-distributed VidXP skill authoring unless repository documentation also changes.
+---
+
+# Maintain VidXP documentation
+
+Keep VidXP documentation accurate, appropriately placed, and readable without
+requiring the reader to know the implementation first.
+
+## Load the project context
+
+1. Read the applicable `AGENTS.md` instructions and `docs/CONTRIBUTING.md`.
+2. Read [references/documentation-map.md](references/documentation-map.md) to
+   identify the document owner and audience.
+3. Read [references/writing-standard.md](references/writing-standard.md) before
+   creating, rewriting, or reviewing human-facing prose.
+4. Inspect `git status` and the relevant diff. Preserve unrelated work and do
+   not stage or commit changes unless the user asks.
+5. Run the established Markdown checks before editing to record the baseline:
+
+   ```bash
+   npx --yes markdownlint-cli2@0.23.2
+   lychee "**/*.md" ".github/**/*.md" ".agents/**/*.md"
+   ```
+
+   If Lychee is unavailable locally, use the pinned container command in
+   `docs/CONTRIBUTING.md` or report that the link check was not run. Record the
+   baseline instead of attributing pre-existing findings to the current change.
+
+## Maintain the documentation
+
+### 1. Define the change
+
+- Identify the behavior, decision, workflow, or correction being documented.
+- Determine whether the task concerns one document, the current diff, or a
+  wider documentation audit.
+- Identify every affected surface: end user, integrator, operator, contributor,
+  maintainer, researcher, or agent.
+
+Do not treat an audience label as proof that prose is suitable for that
+audience. Evaluate the document's vocabulary, sequence, assumptions, and level
+of detail.
+
+### 2. Choose the owner
+
+- Update the smallest document that owns the information.
+- Link to the canonical explanation instead of copying it into several files.
+- Use tutorial, how-to, reference, and explanation as reader-need categories,
+  not as a mandatory directory structure.
+- Keep human contributor guidance separate from agent instructions.
+- Keep repository-maintenance guidance separate from the product-distributed
+  skills under `plugins/vidxp/skills/`.
+- Do not create a documentation changelog, decision log, incident report, or
+  new directory taxonomy unless the repository has adopted it or the user asks.
+
+### 3. Establish evidence
+
+- Verify claims against current code, configuration, tests, workflows, package
+  metadata, or release automation.
+- Prefer the implementation that owns the behavior over prose that merely
+  repeats it.
+- Distinguish confirmed behavior, intended behavior, open questions, and stale
+  documentation. Never present an assumption as a current product guarantee.
+- For time-sensitive external behavior, use an authoritative current source.
+
+### 4. Account for moved or removed information
+
+For every material detail removed during a reduction or rewrite, decide whether
+it is:
+
+- redundant with a named canonical document;
+- moved to a more appropriate named document;
+- obsolete based on repository evidence; or
+- intentionally omitted because it is irrelevant to the target reader.
+
+Restore or relocate useful details that have no remaining owner. Do not silently
+discard operational, compatibility, security, migration, or release information.
+
+### 5. Write for the reader
+
+- Follow [references/writing-standard.md](references/writing-standard.md).
+- Lead with the reader's outcome, decision, or task.
+- Introduce concepts before implementation details and identifiers.
+- Keep commands complete, ordered, and copyable.
+- Use exact internal names only when the reader must type, configure, debug, or
+  modify them.
+- Put architecture and maintainer detail in their owning documents instead of
+  compressing it into end-user prose.
+- Preserve explicit limitations, prerequisites, and security consequences.
+
+### 6. Validate the result
+
+Run checks proportional to the change:
+
+- Read every changed section in full, including its preceding and following
+  paragraphs.
+- Confirm that a reader can identify the purpose, prerequisites, action, and
+  expected result from the document alone.
+- Check relative links, anchors, filenames, heading order, lists, code fences,
+  and rendered tables.
+- Verify commands and terminology against the current implementation. Run only
+  safe checks appropriate to the requested scope.
+- Run `npx --yes markdownlint-cli2@0.23.2` and the Lychee command above again.
+  These tools own Markdown structure and link validation; do not replace them
+  with a custom Markdown parser.
+- Run `git diff --check` and inspect both its output and exit status.
+- Inspect the complete documentation diff for accidental deletion, duplication,
+  unrelated edits, and line-ending churn.
+
+Do not hide warnings behind a successful command or summarize unrun checks as
+passed. Do not call mocked validation end-to-end.
+
+## Report the work
+
+Report:
+
+1. documents changed and why each document owns the change;
+2. material information moved, removed, restored, or intentionally retained;
+3. evidence used to verify behavioral claims;
+4. exact validation commands and results; and
+5. every warning, failed check, or applicable check not run.

.agents/skills/maintain-docs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Maintain VidXP docs"
+  short_description: "Keep VidXP documentation accurate and readable."
+  default_prompt: "Use $maintain-docs to update or review VidXP documentation for the correct reader."

.agents/skills/maintain-docs/references/documentation-map.md

@@ -0,0 +1,63 @@
+# VidXP documentation map
+
+Use this map to select the smallest canonical owner. Recheck the repository
+when paths or responsibilities have changed.
+
+## Public and user-facing documents
+
+| Document | Primary reader | Owns |
+|---|---|---|
+| `README.md` | Prospective and current users | Product purpose, supported outcomes, shortest successful start, and routes to detailed guides |
+| `INSTALLATION_GUIDE.md` | End users | Choosing, installing, preparing, verifying, updating, and troubleshooting a local VidXP setup |
+| `.github/release-intro.md` | People downloading a release | Release download choices and the shortest platform-specific start |
+| `docs/local-api.md` | Application developers and advanced users | Connecting another local or hosted application through HTTP or MCP |
+| `docs/integrations/openai-plugin.md` | Codex and ChatGPT users | Installing, connecting, using, and maintaining the OpenAI integration |
+| `docs/deployment/coolify.md` | Operators | Deploying, securing, validating, backing up, and upgrading the Coolify stack |
+
+Public documents describe outcomes and decisions in product language. Mention
+provider, capability, process, or storage names only when the reader must act on
+them.
+
+## Contributor and maintainer documents
+
+| Document | Primary reader | Owns |
+|---|---|---|
+| `docs/CONTRIBUTING.md` | Human contributors | Fork-based setup, repository orientation, development rules, validation, and pull-request submission |
+| `docs/adding-a-capability.md` | Capability developers | The complete implementation path for adding a capability |
+| `docs/desktop.md` | Desktop developers | Desktop ownership, project layout, local builds, validation, setup behavior, packaging, and signing |
+| `docs/releasing.md` | Maintainers | Release channels, release automation, publication, verification, and recovery |
+| `docs/architecture/platform.md` | System contributors and maintainers | Durable platform boundaries, contracts, invariants, and cross-surface behavior |
+| `docs/deployment/gpu-evaluation.md` | Maintainers evaluating GPU support | Current decision, required boundaries, readiness gaps, validation, and blockers |
+| `docs/benchmarking/README.md` and `docs/benchmarking/` | Researchers and benchmark contributors | Benchmark status, methods, evidence, results, and research history |
+
+Contributor documentation must remain understandable to a person who has not
+seen agent instructions or prior implementation discussions.
+
+## Agent-facing instructions
+
+| Document | Primary reader | Owns |
+|---|---|---|
+| `AGENTS.md` | Repository coding agents | Concise standing repository rules and validation expectations |
+| `.agents/skills/` | Repository coding agents | Repeatable repository-maintenance workflows |
+| `plugins/vidxp/skills/` | Agents using the installed VidXP product | Product operations such as installation, ingestion, and evidence discovery |
+
+Do not move human contributor explanations into `AGENTS.md`. Do not put
+repository-maintenance instructions in product-distributed skills.
+
+## Evidence routes
+
+Use these starting points, then follow the owning implementation:
+
+| Subject | Evidence |
+|---|---|
+| Shared behavior and contracts | `src/vidxp/application.py`, `src/vidxp/control_plane.py`, `src/vidxp/application_models.py` |
+| CLI behavior | `src/vidxp/cli_commands/` and CLI tests |
+| Browser, HTTP, and MCP | `src/vidxp/frontend.py`, `src/vidxp/api_routes/`, `src/vidxp/mcp.py`, and protocol tests |
+| Capabilities and models | `src/vidxp/capabilities/`, capability `requirements.txt` files, and model metadata |
+| Desktop behavior and packaging | `desktop/src/`, `desktop/src-tauri/`, `desktop/package.json`, Desktop manifests, and `.github/workflows/desktop.yml` |
+| Containers and deployment | `Dockerfile`, `compose.yaml`, `compose.coolify.yaml`, and container workflows |
+| Releases | `.github/workflows/release-*.yml`, promotion and channel workflows, release configuration, and package metadata |
+| Benchmarks | `src/vidxp/benchmarks/`, benchmark tests, and recorded evidence under `docs/benchmarking/` |
+
+Treat another document as a navigation aid, not final evidence, when an owning
+implementation or workflow exists.

.agents/skills/maintain-docs/references/writing-standard.md

@@ -0,0 +1,79 @@
+# VidXP documentation writing standard
+
+Apply this standard to human-facing repository documentation. Its purpose is
+reader comprehension, not merely consistent formatting.
+
+## Start from the reader's situation
+
+- State what the reader can accomplish or decide before explaining internals.
+- Make prerequisites visible before the action that depends on them.
+- State the expected result after a command or procedure when it is not obvious.
+- Assume only the knowledge appropriate to the audience in the documentation
+  map.
+- Define a necessary technical term at first use. Replace an unnecessary term
+  with product language.
+
+An `Audience:` label, introductory disclaimer, or heading does not make dense
+contract prose suitable for that audience.
+
+## Give the document a deliberate flow
+
+- Organize procedures in the order the reader performs them.
+- Organize reference material around the choices or interfaces readers look up.
+- Keep rationale next to the decision it explains, without interrupting a
+  procedure with unrelated architecture.
+- Make headings describe a task, decision, or subject. Avoid headings that are
+  meaningful only to someone who already knows the implementation.
+- Give each paragraph one coherent purpose and connect it to the surrounding
+  paragraphs.
+- Use bullets for alternatives, requirements, and short independent facts. Use
+  numbered lists only when order matters.
+- Prefer a table when readers repeatedly compare the same fields. Do not use a
+  table to disguise long prose fragments.
+
+## Write direct prose
+
+- Prefer active voice and concrete subjects.
+- Put the main clause before qualifications when accuracy permits.
+- Split sentences that carry several independent conditions or outcomes.
+- Remove throat-clearing, repeated claims, and generic filler.
+- Avoid compressed noun chains such as “candidate runtime probe contract.” Say
+  who performs the action and what happens.
+- Use “you” for actions the reader performs and the component name for actions
+  the software performs.
+- Preserve necessary qualifications; clarity is not permission to overstate a
+  guarantee.
+
+Do not enforce readability through a mechanical sentence-length limit. A short
+sentence can still be undefined or badly ordered, and a longer sentence can be
+clear when its relationships are explicit.
+
+## Present technical material where it helps
+
+- Put a command immediately after the instruction it carries out.
+- Keep command sequences complete and copyable; do not omit required setup,
+  model preparation, activation, authentication, or verification.
+- Explain placeholders before or directly after the command.
+- Show internal identifiers only when readers must type, configure, inspect, or
+  implement them.
+- Separate normal operation from troubleshooting and implementation detail.
+- Scope warnings precisely: state the affected setup, consequence, and action.
+- Use links for deeper detail instead of inserting an abbreviated architecture
+  document into a user guide.
+
+## Review as a fresh reader
+
+Read the changed document without relying on the implementation discussion and
+answer:
+
+1. Who is this for, based on the prose rather than metadata?
+2. What can the reader accomplish or learn?
+3. What must already be installed, configured, or understood?
+4. What should the reader do next?
+5. What result indicates success?
+6. Which terms or transitions require knowledge found only elsewhere?
+7. Can any paragraph be removed without losing useful information?
+8. Did a reduction remove information that now has no canonical owner?
+
+Revise the document when these answers are missing, scattered, contradictory,
+or dependent on unstated context.

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,74 @@
+name: Bug report
+description: Report a reproducible problem with VidXP.
+title: "[Bug]: "
+body:
+  - type: dropdown
+    id: area
+    attributes:
+      label: Primary affected area
+      options:
+        - Desktop app
+        - CLI
+        - Browser interface
+        - HTTP API
+        - MCP integration
+        - Installation or upgrade
+        - Docker or deployment
+        - Shared behavior across interfaces
+        - Documentation
+        - Other or unsure
+    validations:
+      required: true
+
+  - type: dropdown
+    id: capability
+    attributes:
+      label: Affected capability
+      options:
+        - Dialogue search
+        - Scene search
+        - Action search (videoprism)
+        - Actor matching
+        - Multiple capabilities
+        - Not capability-specific or unsure
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What happened?
+      description: Describe the actual result and what you expected instead.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: How can we reproduce it?
+      description: Include the smallest set of steps, commands, or input that triggers the problem.
+      placeholder: |
+        1.
+        2.
+        3.
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Include the versions and installation or deployment details needed to reproduce the problem.
+      placeholder: |
+        VidXP version:
+        Operating system:
+        Installation or deployment: Desktop-managed, existing installation, uv tool, Docker, Coolify, or source
+        Python version, if applicable:
+    validations:
+      required: true
+
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Logs or other details
+      description: Add relevant logs, screenshots, or files. Remove tokens, private paths, and personal media.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Setup and usage help
+    url: https://grayhat.studio/discord
+    about: Ask questions and get help from the VidXP community on Discord.