@theaiinc/valkyrie-cli

TestFlight feedback

The standalone Valkyrie dashboard accepts normalized TestFlight feedback at POST /api/integrations/testflight/feedback and displays the read-only local queue in its TestFlight feedback panel. See docs/testflight-feedback.md for the payload, HMAC signature, curl example, and production persistence limitations.

@theaiinc/valkyrie-cli

The @theaiinc/valkyrie-cli package contains the Valkyrie QA MCP framework and the typed project configuration contract used by the standalone dashboard. The framework is English-only; the rental product remains separate and Vietnamese-only.

The framework provides QA/MCP orchestration, typed project registries, browser evidence helpers, and autonomous smoke-testing workflows. It is maintained independently from the Arion rental application and its dashboard.

Root Repository Commands

npm test
npm run valkyrie:mcp
npm run valkyrie:explore
npm run valkyrie:report
not included in this repository
not included in this repository

npm test runs the package's safe MCP/unit tests and does not require secrets. The moved dashboard lives in apps/qa and runs at http://localhost:3020:

cd apps/qa
npm install
npm run dev

Automated exploration modes may require the rental app to be running:

npm run dev -- -p 3010
npm run valkyrie:explore

The published CLI exposes both valkyrie (primary) and valk (alias) binaries. Run the MCP server with either alias:

npm install
npx valkyrie --mcp
valkyrie --mcp
valk --mcp

Interactive initialization

Run the configuration wizard from the workspace you want to configure:

valk init
# equivalent:
valkyrie --init
npm run valkyrie:init

The wizard prompts for project id/name, environment, spec and evidence paths, artifact directory, and storage provider (local, gcs, s3, or r2). Cloud providers additionally prompt for non-secret bucket/region/account/endpoint identifiers. It writes .valkyrie/config.yaml and, when absent, .valk.env; credential fields contain only REPLACE_ME placeholders. Existing configuration is shown as the default and is not overwritten without confirmation.

For CI or scripts, no prompt is opened:

VALKYRIE_NON_INTERACTIVE=true valk init
valk init --non-interactive --storage-provider local --force
valk init --non-interactive --storage-provider r2 --bucket qa-artifacts --account-id ACCOUNT_ID

Non-interactive mode keeps an existing config unless --force is supplied. It never reads, prints, or stores credential values. .valk.env is ignored by git; use .valk.env.example as the safe template for local/cloud variable names. valk --mcp remains non-interactive.

The legacy --mode mcp form remains accepted for compatibility. Cursor should invoke the moved scripts/valkyrie.ts entrypoint with --mcp.

Configuration

Defaults are defined in valkyrie.config.yaml:

• Base URL QA: http://localhost:3010.
• Spec package: spec.
• Artifact runtime: qa/valkyrie-runs.
• Current browser evidence manifest: qa/browser-evidence.json.
• Current screenshot evidence: qa/screenshots.

Never print .env values, service-role keys, webhook secrets, or LLM keys in QA logs. To run an LLM-backed mode, provide LLM_PROVIDER, LLM_MODEL, and LLM_API_KEY through a private local/CI environment.

Project registration uses the private .valk.env file for VALKYRIE_API_KEY; the CLI does not load the dashboard or registry .env. The key is never written to generated configuration or printed.

External QA UI

The read-only QA dashboard is maintained in apps/qa. It does not read .env in the browser or write rental application data. With AEGIS_AUTH_REQUIRED=true, its server routes require an existing Aegis identity and only expose authorized project context.

Multiple projects

The shared schema is in projects/types.ts. A project has an id, display metadata, environment.baseUrl, plans, testCases, evidence, blockers, an evidenceRun, and aggregate stats. The registry helper in projects/registry.ts validates duplicate IDs.

The arion-rent project is assembled from the existing spec/*, QA_TEST_PLAN.md, QA_EVIDENCE.md, and qa/browser-evidence.json data in the Arion repository. The Valkyrie project (stable id qa-framework) covers this package and the standalone dashboard using its own tests, specs, and documentation. It has no screenshot evidence until a dedicated framework browser run captures it.

Copyable test-case references

Each standalone-dashboard test-case card and detail modal offers Copy reference. It copies the stable project, environment, test-plan, and test-case IDs from the typed registry, plus names, status, evidence/screenshot information, and a suggested coding-agent context block. See docs/test-case-references.md for the exact format and clipboard fallback behavior. The prompt is context for an agent request only; it does not imply automatic fixing.

To add a project, define a typed object in projects, give it a unique stable id, set its environment, plans, test cases, blockers, and real evidence references, then add it to the createQaProjectRegistry([...]) call used by the dashboard. This is a typed TypeScript configuration path; it contains no secrets. Changes require restarting the QA dev server (and rebuilding for production). There is no runtime persistence or authentication for project configuration.

Each project declares one or more URL-only environments with a stable id, display name, baseUrl, optional apiUrl, isDefault, and status (active, inactive, or planned). Add local, staging, or production environments to the project object; the dashboard selector and query state derive from that list without UI changes. Evidence may optionally set environmentId; evidence for another environment is not shown as current proof, and missing evidence remains explicitly unavailable.

Arion Specs

The spec files are tailored to the current MVP:

• spec/project_config.yaml: route, manifest, and app startup configuration.
• spec/journey_graph.yaml: landing page, public booking, payments, owner dashboard, reporting, and webhooks.
• spec/domain_rules.yaml: Vietnamese rental-app copy, missing Supabase schema, private Storage, QR/bank transfer payments, and OM secret headers.
• spec/blockers.yaml: setup states, disabled forms, missing payment data, destructive confirmations, and the secret-output hard stop.

The Arion rental app and its QA dashboard remain in their own repository; this standalone package should reference external projects through explicit environment paths when needed.