{"id":48669360,"url":"https://github.com/yuan-cloud/vifei-suite-public","last_synced_at":"2026-04-10T11:35:17.379Z","repository":{"id":339663680,"uuid":"1162936588","full_name":"yuan-cloud/vifei-suite-public","owner":"yuan-cloud","description":"Deterministic, local-first CLI/TUI for AI Agent rerun evidence, incidental forensics, and fail-closed share-safe exports.","archived":false,"fork":false,"pushed_at":"2026-03-31T01:46:56.000Z","size":2129,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T04:47:15.087Z","etag":null,"topics":["ai-agents","auditability","cli","deterministic","eventlog","forensics","indient-response","jsonl","local-first","observability","redaction","redactionsecurity","replay","rust","tui"],"latest_commit_sha":null,"homepage":"https://github.com/yuan-cloud/vifei-suite-public","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yuan-cloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-20T21:58:10.000Z","updated_at":"2026-03-31T01:46:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yuan-cloud/vifei-suite-public","commit_stats":null,"previous_names":["yuan-cloud/vifei-suite-public"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/yuan-cloud/vifei-suite-public","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuan-cloud%2Fvifei-suite-public","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuan-cloud%2Fvifei-suite-public/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuan-cloud%2Fvifei-suite-public/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuan-cloud%2Fvifei-suite-public/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yuan-cloud","download_url":"https://codeload.github.com/yuan-cloud/vifei-suite-public/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuan-cloud%2Fvifei-suite-public/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31641442,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","auditability","cli","deterministic","eventlog","forensics","indient-response","jsonl","local-first","observability","redaction","redactionsecurity","replay","rust","tui"],"created_at":"2026-04-10T11:35:16.423Z","updated_at":"2026-04-10T11:35:17.371Z","avatar_url":"https://github.com/yuan-cloud.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vifei Suite\n\n[![CI](https://img.shields.io/github/actions/workflow/status/yuan-cloud/vifei-suite-public/ci.yml?branch=main\u0026event=push\u0026label=CI)](https://github.com/yuan-cloud/vifei-suite-public/actions/workflows/ci.yml)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nDeterministic, local-first run evidence for AI agent workflows.\n\nVifei records canonical run truth as an append-only EventLog, then projects that truth into operator views and proof artifacts you can rerun and verify.\n\nPresentation showcase: `docs/showcase/index.md`\n\n## First-Screen Product Vibe\n\nTrust-first cockpit with deterministic proof surfaces:\n\n![Incident Lens Showcase](docs/assets/readme/incident-lens-showcase.svg)\n\n![Forensic Lens Showcase](docs/assets/readme/forensic-lens-showcase.svg)\n\n![Truth HUD Showcase](docs/assets/readme/truth-hud-showcase.svg)\n\nQuick launch commands:\n\n```bash\nscripts/demo/trust_demo_cut.sh /tmp/vifei_trust_cut fixtures/small-session.jsonl\nscripts/demo/visual_showcase_cut.sh /tmp/vifei_visual_cut\nscripts/demo/package_launch_bundle.sh .tmp/launch-media-bundle\n```\n\n## At a Glance\n\n- Deterministic replay evidence you can rerun and verify locally.\n- Incident-first and forensic-first views with an always-visible Truth HUD.\n- Share-safe export that fails closed with explicit refusal reports.\n\n## Why This Exists\n\nMost agent workflows have logs but weak replay guarantees under stress. Vifei keeps truth auditable when pressure rises.\n\n- Canonical ordering uses `commit_index` from one append writer.\n- Truth stays intact under overload; only projection quality degrades.\n- Share-safe export refuses unsafe bundles and emits explicit refusal reports.\n\n## Why This Matters for Revenue Ops\n\nTeams lose deals when execution context is fragmented across tools and people. Vifei demonstrates an engineering posture that keeps operational workflows fast and trustworthy.\n\n- Faster root-cause analysis for stalled workflow states through deterministic replay.\n- More consistent follow-through with explicit, inspectable run evidence.\n- Safer automation boundaries with fail-closed export and refusal diagnostics.\n\n## 60-Second Quickstart\n\n1. Run deterministic stress Tour:\n\n```bash\ncargo run -p vifei-tui --bin vifei -- tour fixtures/large-stress.jsonl --stress --output-dir tour-output\n```\n\n2. Confirm proof artifacts:\n\n```bash\nls -1 tour-output\ncat tour-output/viewmodel.hash\ncat tour-output/metrics.json\n```\n\n3. Optional human-readable CLI surface check:\n\n```bash\ncargo run -p vifei-tui --bin vifei -- --human --help\n```\n\nExpected artifact files:\n\n- `metrics.json`\n- `viewmodel.hash`\n- `ansi.capture`\n- `timetravel.capture`\n\n## Trust Signals (What You Can Verify Yourself)\n\n| Claim | How to verify |\n|---|---|\n| Replay determinism | Run Tour twice and compare `viewmodel.hash` |\n| Tier A truth protection | Confirm `tier_a_drops` is `0` in `metrics.json` |\n| Share-safe export posture | Run export with `--share-safe`; inspect refusal report behavior |\n| Constitutional alignment | Run `cargo test` (`docs_guard` enforces constitutional drift checks) |\n\n## Core Workflows\n\n### Desktop operator flow (full triage)\n\nUse this path during active investigation on a full terminal.\n\n- Human CLI adapter track (operator-readable snippets): `docs/showcase/adapter-human-cli-track.md`\n- Robot JSON adapter track (automation snippets + contract expectations): `docs/showcase/adapter-robot-json-track.md`\n- Refusal and safety adapter track (security and governance proofs): `docs/showcase/adapter-refusal-safety-track.md`\n\n### Determinism check (rerun hash)\n\n```bash\ncat tour-output/viewmodel.hash\ncargo run -p vifei-tui --bin vifei -- tour fixtures/large-stress.jsonl --stress --output-dir tour-output-rerun\ncat tour-output-rerun/viewmodel.hash\n```\n\nExpected result: both hash files match.\n\nShortcut demo script:\n\n```bash\nscripts/demo/determinism_duel.sh --fast\n```\n\nUse `--full` for stress-grade replay duel.\n\n### View an EventLog in TUI\n\n```bash\ncargo run -p vifei-tui --bin vifei -- view docs/assets/readme/sample-eventlog.jsonl\n```\n\nRun in a real interactive terminal (TTY).\n\n### FrankenTUI Cockpit (sidecar viewer)\n\nA standalone read-only cockpit built on [FrankenTUI](https://github.com/Dicklesworthstone/frankentui) with animated gradient title, live spinner, color-coded event breakdown, and deterministic BLAKE3 viewmodel hash.\n\n![Cockpit Sample](docs/assets/ftui-demos/cockpit-sample.gif)\n\n```bash\ncargo run --release -p vifei-ftui -- --events docs/assets/readme/sample-eventlog.jsonl\n```\n\nHeadless mode for CI and scripted verification:\n\n```bash\ncargo run --release -p vifei-ftui -- --events docs/assets/readme/sample-eventlog.jsonl --headless\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eExport-clean eventlog (3 events)\u003c/summary\u003e\n\n![Cockpit Export Clean](docs/assets/ftui-demos/cockpit-export-clean.gif)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eRefusal eventlog (1 event)\u003c/summary\u003e\n\n![Cockpit Refusal](docs/assets/ftui-demos/cockpit-refusal.gif)\n\n\u003c/details\u003e\n\n### Mobile or narrow-screen proof scan\n\nUse this path when you need high-signal proof checks quickly in limited width.\n\n1. Run Tour and check hash + drops.\n2. Run refusal radar for export safety proof.\n3. Read the latest bakeoff report for one-file summary evidence.\n\n```bash\nscripts/demo/determinism_duel.sh --fast\nscripts/demo/refusal_radar.sh --fast\ncat .tmp/competitor-bakeoff/run-*/bakeoff-report.json\n```\n\n### Showcase profile (visual demo mode)\n\n```bash\ncargo run -p vifei-tui --bin vifei -- \\\n  view docs/assets/readme/sample-eventlog.jsonl --profile showcase\n```\n\n`showcase` only changes presentation chrome and emphasis; truth ordering and proof semantics remain unchanged.\n\n### Showcase gallery\n\nIncident Lens (standard):\n\n![Incident Lens](docs/assets/readme/incident-lens.svg)\n\nIncident Lens (showcase):\n\n![Incident Lens Showcase](docs/assets/readme/incident-lens-showcase.svg)\n\nForensic Lens (showcase):\n\n![Forensic Lens Showcase](docs/assets/readme/forensic-lens-showcase.svg)\n\nTruth HUD (showcase):\n\n![Truth HUD Showcase](docs/assets/readme/truth-hud-showcase.svg)\n\n### Export with share-safe checks\n\n```bash\ncargo run -p vifei-tui --bin vifei -- export \\\n  docs/assets/readme/sample-export-clean-eventlog.jsonl \\\n  --share-safe \\\n  --output out/bundle.tar.zst \\\n  --refusal-report out/refusal-report.json\n```\n\nRefusal Radar demo script:\n\n```bash\nscripts/demo/refusal_radar.sh --fast\n```\n\n### Incident evidence pack (one command)\n\n```bash\ncargo run -p vifei-tui --bin vifei -- incident-pack \\\n  docs/assets/readme/sample-export-clean-eventlog.jsonl \\\n  docs/assets/readme/sample-export-clean-eventlog.jsonl \\\n  --output-dir out/incident-pack\n```\n\nThis writes deterministic local artifacts (`compare/delta.json`, replay summaries, share-safe bundles, and `manifest.json`) and fails closed with `EXPORT_REFUSED` if scanner findings block export.\n\nInput format flags for mixed-source comparisons:\n\n```bash\ncargo run -p vifei-tui --bin vifei -- incident-pack \\\n  fixtures/small-session.jsonl \\\n  docs/assets/readme/sample-export-clean-eventlog.jsonl \\\n  --left-format cassette \\\n  --right-format eventlog \\\n  --output-dir out/incident-pack\n```\n\nManifest input labels are share-safe file labels (not absolute local paths).\n\n### Deterministic run comparison\n\n```bash\ncargo run -p vifei-tui --bin vifei -- compare \\\n  docs/assets/readme/sample-export-clean-eventlog.jsonl \\\n  docs/assets/readme/sample-export-clean-eventlog.jsonl\n```\n\nOptional mixed-format compare:\n\n```bash\ncargo run -p vifei-tui --bin vifei -- compare \\\n  fixtures/small-session.jsonl \\\n  docs/assets/readme/sample-export-clean-eventlog.jsonl \\\n  --left-format cassette \\\n  --right-format eventlog\n```\n\nExit behavior:\n- `0` when no divergence is found\n- `5` when divergences are found (`DIFF_FOUND` envelope in robot mode)\n\n### Competitor bakeoff harness (objective proof demo)\n\n```bash\nscripts/demo/competitor_bakeoff.sh --fast\n```\n\nThis produces a timestamped proof bundle under `.tmp/competitor-bakeoff/` with:\n- determinism duel hash agreement\n- refusal-report blocked-item evidence\n- Truth HUD explainability token checks\n- incident-pack artifact validation\n\n### Proofs (latest full local run)\n\nRun:\n\n```bash\nscripts/demo/competitor_bakeoff.sh --full\n```\n\nInspect:\n\n```bash\ncat .tmp/competitor-bakeoff/run-*/bakeoff-report.json\n```\n\nLatest run summary (`2026-02-18T22:36:20Z`):\n- determinism hash agreement: `000573091386a86cabe6935bbe997897a83f42cf89595238e55c2f9c8d45eda6`\n- refusal semantics: `blocked_count=4`\n- explainability tokens present: `Level`, `Agg`, `Pressure`, `Drops`, `Export`, `Version`\n- incident pack artifacts validated: `manifest.json` and `compare/delta.json`\n\n### Final verification evidence bundle\n\nGenerate governance + demo evidence in one place:\n\n```bash\nmkdir -p .tmp/final-audit\nscripts/testing/check_bead_closure_evidence.py \\\n  --audit-output-json .tmp/final-audit/bead-risk-parity.json \\\n  --audit-output-markdown .tmp/final-audit/bead-risk-parity.md\nscripts/testing/validate_defer_register.py docs/testing/defer-register-v0.1.json\nscripts/testing/check_coverage_contract.sh\nscripts/testing/demo_smoke.sh .tmp/final-audit/demo-smoke\n```\n\nPrimary outputs:\n- `.tmp/final-audit/bead-risk-parity.json`\n- `.tmp/final-audit/bead-risk-parity.md`\n- `.tmp/final-audit/demo-smoke/duel/*/viewmodel.hash`\n- `.tmp/final-audit/demo-smoke/radar/refusal-report.json`\n- `.tmp/final-audit/demo-smoke/bakeoff/*/bakeoff-report.json`\n\n### Live Incident Wall assets\n\n```bash\nscripts/demo/live_incident_wall.sh --fast\n```\n\nThis prepares premium showcase wall assets under `docs/assets/readme/`.\n\n### Record a showcase cast\n\n```bash\nscripts/capture_showcase_cast.sh --fast /tmp/vifei-showcase-cast\n```\n\nRequires `asciinema`; output is a replayable `.cast` file for launch/demo channels.\n\n### Robot mode for AI agents\n\nUse machine-readable mode for automation:\n\n```bash\ncargo run -p vifei-tui --bin vifei -- \\\n  --json tour fixtures/large-stress.jsonl \\\n  --stress --output-dir tour-output\n```\n\nBehavior contract:\n\n- `--json` returns compact structured output for success and errors.\n- When stdout is piped, CLI auto-switches to JSON (unless `--human` is set).\n- Error payloads include `code`, `message`, and `suggestions`.\n- Parser authority is explicit: `clap` owns subcommand aliases and parse semantics.\n- Normalization is bounded to known option spelling repairs and never rewrites positionals (including after `--`).\n\nForce human-readable output even when piping:\n\n```bash\ncargo run -p vifei-tui --bin vifei -- \\\n  --human --help\n```\n\nStrict trust verification command:\n\n```bash\ncargo run -p vifei-tui --bin vifei -- \\\n  --json verify --strict --full --output-dir verify-output\n```\n\nThis emits a single structured result that checks determinism stability, Tier A drop safety, refusal semantics, and explainability token presence.\n\nRobot JSON contract keys (`schema_version=vifei-cli-robot-v1.1`):\n\n| Key | Type | Notes |\n|---|---|---|\n| `schema_version` | string | Contract version for parsers |\n| `ok` | bool | Success/failure discriminator |\n| `code` | string | Stable status code (`OK`, `INVALID_ARGS`, `NOT_FOUND`, `EXPORT_REFUSED`, `RUNTIME_ERROR`, `DIFF_FOUND`) |\n| `message` | string | Human-readable summary |\n| `suggestions` | array[string] | Actionable next commands or hints |\n| `exit_code` | number | Process exit code mirror |\n| `data` | object | Success payload (present on success envelopes) |\n| `notes` | array[string] | Optional normalization notes when intent-repair was applied |\n\nExit codes:\n\n- `0`: success\n- `1`: not found\n- `2`: invalid args\n- `3`: export refused (share-safe scanner refusal)\n- `4`: runtime error\n- `5`: diff found (compare divergence)\n\n## Architecture Snapshot\n\n```mermaid\nflowchart TD\n    A[Agent Cassette JSONL] --\u003e B[Importer]\n    B --\u003e C[Append Writer\u003cbr/\u003eassigns commit_index]\n    C --\u003e D[EventLog JSONL + Blob Store]\n    D --\u003e E[Reducer]\n    E --\u003e F[Projection]\n    F --\u003e G[ViewModel]\n    G --\u003e H[Incident Lens + Forensic Lens + Truth HUD]\n    D --\u003e I[Tour stress harness]\n    I --\u003e J[metrics.json]\n    I --\u003e K[viewmodel.hash]\n    I --\u003e L[ansi.capture]\n    I --\u003e M[timetravel.capture]\n```\n\nWorkspace crates:\n\n- `crates/vifei-core`: event schema, append writer, reducer, projection\n- `crates/vifei-import`: Agent Cassette importer\n- `crates/vifei-export`: bundle export and share-safe scanning\n- `crates/vifei-tour`: stress harness and proof artifact emission\n- `crates/vifei-tui`: CLI and terminal UI lenses\n- `tools/vifei-ftui`: FrankenTUI cockpit sidecar viewer\n\n## Technical Docs\n\n- `docs/CAPACITY_ENVELOPE.md`\n- `docs/BACKPRESSURE_POLICY.md`\n- `docs/UX_SCOPE.md`\n- `docs/UX_MODALITY_MATRIX.md`\n- `docs/UX_VISUAL_TONE.md`\n- `docs/PUBLIC_REPO_SETTINGS_CHECKLIST.md`\n\n## Additional Docs\n\n- `docs/TESTING.md`\n- `docs/DEMO_SCRIPT.md`\n- `docs/RELEASE_TRUST_VERIFICATION.md`\n- `docs/RELEASE_PACKAGING_CHECKLIST.md`\n\n## Community and Security\n\n- `CONTRIBUTING.md`: contribution expectations and report quality checklist\n- `SUPPORT.md`: support channels and triage priorities\n- `SECURITY.md`: private vulnerability reporting policy\n- `docs/COMMUNITY_TRIAGE_PLAYBOOK.md`: maintainer triage and severity flow\n- `.github/ISSUE_TEMPLATE/`: issue intake forms for bug and determinism reports\n- `.github/pull_request_template.md`: PR evidence and risk template\n\n## Status\n\nVifei v0.1 implements the core truth pipeline with deterministic replay, share-safe export, and evidence artifacts.\n\n## Development\n\n```bash\ncargo fmt --check\ncargo clippy --all-targets -- -D warnings\ncargo test\n```\n\n## Troubleshooting\n\n### `--stress flag is required`\n\n`tour` intentionally refuses non-stress mode in v0.1. Add `--stress`.\n\n### `Export without secret scanning is not supported`\n\n`export` requires `--share-safe`.\n\n### Tour hash mismatch across reruns\n\nTreat as determinism regression. Re-run on an idle machine, then inspect recent reducer/projection changes.\n\n### `view` fails on fixture path\n\n`view` expects EventLog JSONL, not Agent Cassette fixture JSONL.\n\n## README Assets\n\nReference captures and visuals live under `docs/assets/readme/`:\n\n- `docs/assets/readme/incident-lens.txt`\n- `docs/assets/readme/incident-lens.svg`\n- `docs/assets/readme/incident-lens-showcase.txt`\n- `docs/assets/readme/incident-lens-showcase.svg`\n- `docs/assets/readme/forensic-lens.txt`\n- `docs/assets/readme/forensic-lens.svg`\n- `docs/assets/readme/forensic-lens-showcase.txt`\n- `docs/assets/readme/forensic-lens-showcase.svg`\n- `docs/assets/readme/truth-hud-degraded.txt`\n- `docs/assets/readme/truth-hud-degraded.svg`\n- `docs/assets/readme/truth-hud-showcase.txt`\n- `docs/assets/readme/truth-hud-showcase.svg`\n- `docs/assets/readme/export-refusal.txt`\n- `docs/assets/readme/architecture.mmd`\n\nRefresh deterministically:\n\n```bash\nscripts/refresh_readme_assets.sh\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuan-cloud%2Fvifei-suite-public","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyuan-cloud%2Fvifei-suite-public","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuan-cloud%2Fvifei-suite-public/lists"}