aperta-cli 1.0.0-beta.1 → 1.0.0-beta.3

package/README.md

@@ -1,310 +1,183 @@
-# Aperta
-
-**Your code works. Could you explain why?**
-
-AI coding agents make it easy to ship code you cannot explain. Aperta measures
-that comprehension gap before it becomes a debugging, maintenance, or ownership
-problem. It records what changed, asks for a quick self-rating, and shows where
-the codebase has outrun your understanding. It records explanations but does not
-grade them.
-
-The current 1.0 beta combines a provider-neutral coding-agent harness with a
-local comprehension system. It observes changes from any editor or agent,
-executes bounded work in disposable Git worktrees, verifies outcomes, and turns
-the resulting evidence into review sessions, a learning journal, and a durable
-Proof Graph.
-
-The local Vue dashboard includes:
-
-- Agent Workbench with persistent multi-turn conversations
-- Aperta Native, Cursor Agent, Claude Code, and OpenCode execution runtimes
-- OpenAI, Anthropic, Google Gemini, DeepSeek, Ollama, OpenRouter, Groq, and
-  OpenAI-compatible model profiles
-- staged, unstaged, and untracked Git views
-- syntax-highlighted source, diffs, agent responses, and execution output
-- repository, impact, and behavioral Proof Graphs
-- guided ownership sessions, Review Queue, Learn Next, and Learning Journal
-- local harness reliability, verification, repair, and trusted-keep metrics
-
-Repository evidence stays in private per-user storage unless the user explicitly
-invokes a configured model. Credentials never enter project memory.
-
-## How the harness is divided
-
-Aperta deliberately separates three responsibilities:
-
-- **Model APIs reason.** A configured model can plan, explain, and choose from
-  Aperta's bounded tools.
-- **Agent runtimes execute.** Aperta Native, Cursor Agent, Claude Code, or
-  OpenCode can inspect and edit an isolated workspace. External runtimes keep
-  their own authentication and model configuration.
-- **Aperta owns trust.** Aperta selects the skill contract, constrains
-  capabilities, captures actions, runs deterministic checks and localhost
-  probes, controls promotion, and records proof and learning evidence.
-
-Changing the runtime or model never gives it authority to declare its own work
-correct or understood.
-
-## Aperta Coach (optional AI)
-
-Aperta Coach turns the deterministic ownership brief into an adaptive change
-debrief. It can orient the maintainer and personalize trace, failure-mode,
-evidence, and debugging questions. Model output remains visibly AI-generated:
-it cannot change Trust Kernel relationships, mark runtime evidence as proven,
-grade prose, or award ownership. Returned file citations are accepted only when
-they match files in the captured change.
-
-Coach is provider-neutral and configured through environment variables so API
-keys never enter the project config or ledger. It supports native OpenAI,
-Anthropic, Google Gemini, DeepSeek, and Ollama APIs; OpenRouter and Groq
-gateways; and any OpenAI-compatible HTTPS or local endpoint, including LM
-Studio.
+<h1 align="center">Aperta</h1>
 
-```sh
-# OpenAI (OPENAI_API_KEY is read automatically)
-export OPENAI_API_KEY="..."
+<p align="center"><strong>Own the code AI writes.</strong></p>
 
-# Anthropic
-export APERTA_AI_PROVIDER="anthropic"
-export ANTHROPIC_API_KEY="..."
-export APERTA_AI_MODEL="your-model-id"
+<p align="center">
+  Aperta captures each code change, runs project checks, connects claims to
+  evidence, and helps you explain the result before it reaches your main branch.
+</p>
 
-# Google Gemini
-export APERTA_AI_PROVIDER="google"
-export GOOGLE_API_KEY="..."
-export APERTA_AI_MODEL="your-model-id"
+<p align="center">
+  <a href="https://aperta-six.vercel.app/">Website</a> ·
+  <a href="https://www.npmjs.com/package/aperta-cli">npm</a> ·
+  <a href="https://github.com/Vequan23/aperta/issues">Issues</a> ·
+  <a href="CONTRIBUTING.md">Contributing</a>
+</p>
 
-# DeepSeek
-export APERTA_AI_PROVIDER="deepseek"
-export DEEPSEEK_API_KEY="..."
-export APERTA_AI_MODEL="your-model-id"
+<p align="center">
+  <a href="https://www.npmjs.com/package/aperta-cli"><img alt="npm beta" src="https://img.shields.io/npm/v/aperta-cli/beta?label=npm%20beta&color=1686cc"></a>
+  <a href="https://github.com/Vequan23/aperta/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Vequan23/aperta/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+  <img alt="Node 24 LTS recommended" src="https://img.shields.io/badge/node-24%20LTS%20recommended-3c873a">
+</p>
 
-# OpenRouter or Groq
-export APERTA_AI_PROVIDER="openrouter" # or groq
-export OPENROUTER_API_KEY="..."        # or GROQ_API_KEY
-export APERTA_AI_MODEL="provider/model-id"
+> [!IMPORTANT]
+> **Public beta:** Aperta is ready for evaluation on real local projects. Its
+> interfaces and evidence schema may evolve before the first stable release.
 
-# Local Ollama — no API key required
-export APERTA_AI_PROVIDER="ollama"
-export APERTA_AI_MODEL="qwen2.5-coder"
+## AI can write the patch. You still own the result.
 
-# Any OpenAI-compatible provider
-export APERTA_AI_PROVIDER="openai-compatible"
-export APERTA_AI_BASE_URL="https://provider.example/v1"
-export APERTA_AI_MODEL="provider/model-id"
-export APERTA_AI_API_KEY="..."
+AI agents can produce a convincing patch in minutes. They do not automatically
+give a maintainer the evidence or understanding needed to safely own that patch
+for years.
 
-aperta dashboard
-```
+Aperta closes that gap. It is a local review and learning system that:
 
-`APERTA_AI_MODEL` overrides every provider default. Remote custom endpoints
-must use HTTPS; plaintext HTTP is accepted only for loopback model servers.
-The evidence bundle is sent to the configured provider only when the user
-explicitly clicks **Personalize this debrief**.
-
-The dashboard also provides **Model Settings** for reusable provider profiles.
-Profile metadata is stored globally in `~/.aperta/settings.json`, never in a
-repository. On macOS, supplied API keys are stored in Keychain and never
-returned to the browser; environment variables remain supported for automated
-and cross-platform use.
-
-## Repository comprehension explorer
-
-The Repository Map is a navigable tree of Git-visible tracked and untracked
-files. Ignored files—including ignored `.env` files—are excluded at the server
-boundary. Selecting a file opens a bounded, syntax-highlighted read-only source
-view with its confidence, authorship ratio, captured churn, and ownership
-history. Binary files are identified without rendering their contents, and
-text previews are limited to 1 MB.
-
-## Agent Workbench
-
-The Agent Workbench is Aperta's controlled action plane. An active model profile
-can run a bounded implementation loop inside a disposable Git worktree using
-repository list, read, search, and write tools plus allowlisted project checks,
-detected local-service startup, and localhost HTTP probes. The agent has no
-arbitrary shell or remote-network tool and cannot access ignored files,
-credential-bearing files, `.git`, or `.comprehension`. Existing files must be
-read before they can be rewritten; runs are capped at 48 implementation
-actions, 20 writes, 300 KB per file, and 1 MB of total writes.
-
-Alternatively, Aperta can delegate the isolated execution loop to an installed
-Cursor Agent, Claude Code, or OpenCode CLI. Aperta still owns the disposable
-workspace, exact changed-file capture, verification loop, action record, and
-promotion gate. Read-only requests discard unexpected runtime mutations.
-
-Completed runs produce a retained local action record and a syntax-highlighted
-patch. Aperta detects allowlisted project checks for Maven, Gradle, Node package
-scripts, Python, Go, and Cargo, runs them inside the disposable worktree, and
-gives the agent up to three bounded attempts to repair failures. Changes,
-verification output, and live activity have separate review surfaces, and a
-run with failing checks cannot be promoted. Analysis-only runs use a dedicated
-readable response view instead of pretending an empty patch exists.
-
-The source repository remains unchanged until the maintainer checks the
-promotion acknowledgement and explicitly applies the patch. Before promotion,
-Aperta compares the real repository tree with the run's starting tree and
-refuses to apply over newer work. A promoted patch then enters the normal Git
-observer, proof, ownership-session, journal, and recall workflow.
-
-Every run also carries a durable execution contract: goal, ordered plan,
-constraints, risks, acceptance criteria, evidence status, deterministic
-critique, and promotion decision. Aperta records the pre-change project baseline
-separately from post-change checks, so a green result cannot hide a repository
-that was already failing. Passing generic checks proves project health; it does
-not by itself prove the user's requested behavior.
-
-## Skill Contracts
-
-Every run receives a deterministic, provider-neutral Skill Contract before a
-model or external runtime acts. The current built-in contracts cover debugging,
-project verification, runtime observation, implementation, code explanation,
-and repository exploration. Each contract declares:
-
-- the capabilities the runtime may use
-- ordered execution phases
-- required proof before completion
-- learning objectives that feed the understanding loop
-
-Models may refine a plan, but they cannot remove the skill's required proof or
-expand its tool authority. The selected skill is visible in the Workbench and
-stored as evidence in the Proof Graph.
-
-## Git and universal capture
-
-Aperta's observer tracks stable staged, unstaged, untracked, and committed
-changes regardless of whether they came from a human, an IDE, or an agent. The
-Git Changes view shows the current working tree independently from captured
-learning sessions. Agent attribution is additional evidence, not a requirement
-for the comprehension workflow.
-
-## Harness Intelligence
-
-Harness Health turns retained local runs into an improvement loop. It measures
-first-pass verification, repair recovery, tool reliability, promotion rate,
-provider latency, structured error classes, and an approximate Trusted Keep
-Rate for promoted additions that remain in the working repository. Results are
-broken down by provider, model, and bounded tool action so model and harness
-changes can be compared instead of judged by anecdote.
-
-Telemetry contains run metadata, timings, bounded error messages, and patch-line
-survival counts. It is computed locally; Aperta does not export source code,
-prompts, credentials, or repository evidence to an analytics service. Unknown
-errors are surfaced as harness defects rather than silently folded into an
-"agent failed" bucket.
-
-The Impact Graph connects changed and removed code surfaces to repository
-callers, imported dependencies, Spring configuration, API entry points, and
-tests. It distinguishes structural evidence from unproven behavior and warns
-when a saved explanation overlaps code that changed again. The analyzers are
-language-specific and pluggable; the current beta starts with Java and
-TypeScript rather
-than claiming regex can provide compiler-level semantics for every language.
-
-The repository Proof Graph unifies claims from captured changes and agent runs
-with the evidence that supports them: selected skills, diffs, checks, runtime
-observations, human explanations, and ownership reviews. A claim can be proven,
-understood, supported, unproven, stale, or regressed. Later changes invalidate
-only connected claims, preserving an auditable answer to both “does this work?”
-and “can the maintainer explain it?”
-
-The Proof Engine detects Maven, Gradle, npm, pnpm, or Yarn from project-owned
-manifests and wrappers. From the Impact Graph, a developer can explicitly run
-the relevant changed tests, retain the bounded result in the append-only local
-ledger, and see graph surfaces move from inferred or unproven to proven—or to
-regressed when the runner fails. Aperta also keeps uncovered behaviors visible
-as proposed probes instead of treating a green test command as universal proof.
-
-## Install and run
-
-Requires Node.js 22.6 or newer and Git.
+- captures staged, unstaged, untracked, human, and agent-authored changes;
+- runs agent work in disposable Git worktrees instead of your live repository;
+- verifies results with project checks, runtime observations, and bounded probes;
+- connects claims, code, tests, actions, and human understanding in a Proof Graph;
+- turns risky changes into focused ownership reviews and scheduled recall; and
+- keeps private developer memory outside the repository by default.
 
-```sh
-npm install --global aperta-cli@beta
-```
+**Aperta does not grade prose or pretend an LLM can certify understanding.** It
+records evidence, exposes uncertainty, and leaves the final judgment with the
+person responsible for the software.
 
-To develop Aperta itself from source instead:
+If that is the future you want for AI-assisted development, consider starring
+the repository. It helps other builders find the project.
 
-```sh
-git clone https://github.com/Vequan23/aperta.git
-cd aperta
-npm install
-npm test
-npm run build
-npm link
-```
+## Try it in 60 seconds
 
-Initialize the repository you want Aperta to track:
+Requires Git and a supported Node.js LTS release. **Node 24 LTS is recommended**;
+Node 22.12 or newer remains supported through its maintenance window.
 
 ```sh
+npm install --global aperta-cli@beta
+
 cd /path/to/your/repository
 aperta init
-aperta status
 aperta dashboard
 ```
 
-`aperta init` starts the universal observer automatically. On macOS it installs
-a private per-project login service, so observation returns after login and is
-restarted if the process crashes. It captures stable staged, unstaged,
-untracked, and committed changes from any coding tool. Manage it explicitly with:
+`aperta init` starts the local observer. The dashboard opens a repository
+workspace containing Agent Work, Git Changes, Changes to Review, the Proof
+Graph, Review Notes, and Agent Reliability.
+
+Run an existing coding agent through Aperta:
 
 ```sh
-aperta start
-aperta status
-aperta stop
+aperta run --intent "Add passwordless login" -- opencode
 ```
 
-Changes are grouped after a short quiet period rather than recorded once per
-keystroke. Agent adapters add model, prompt, and session provenance when it is
-available; unattributed activity remains explicitly unknown.
+Or use Aperta Native from Agent Work. The patch remains isolated until
+you review its changes and evidence and explicitly promote it.
 
-Every initialized repository is added to the local `~/.aperta/projects.json`
-registry. The dashboard project picker can switch between registered
-repositories without exposing arbitrary filesystem browsing. Each project keeps
-its own ledger, observer, branch state, queue, journal, and ownership history.
+## The trust and learning loop
 
-For dashboard development with live reload, run `npm run dev` from the cloned
-Aperta repository and open the local URL Vite prints.
+```mermaid
+flowchart LR
+  change["Any code change"] --> capture["Capture the exact diff"]
+  capture --> impact["Map impact and risk"]
+  impact --> verify["Run checks and probes"]
+  verify --> graph["Update the Proof Graph"]
+  graph --> own["Demonstrate ownership"]
+  own --> journal["Retain and revisit knowledge"]
+  journal --> change
+```
 
-The standalone Vue marketing site lives in `marketing/` and uses the same Snow
-Leopard/Aqua visual language as the product:
+Every later change can invalidate only the claims it touches. Aperta preserves
+useful evidence while making stale certainty visible.
 
-```sh
-npm run dev:marketing
-npm run build:marketing
-```
+## Why this is not just another agent wrapper
 
-The repository-level `vercel.json` deploys `marketing/dist`, so the repository
-can be imported directly into Vercel without additional build configuration.
+| | Typical coding-agent loop | Aperta |
+| --- | --- | --- |
+| Primary goal | Produce a plausible answer or patch | Produce reviewable code, proof, and understanding |
+| Workspace | Often edits the live tree | Uses a disposable Git worktree until promotion |
+| Verification | Agent reports success | Aperta runs deterministic checks and captures output |
+| Trust | Model evaluates its own work | Aperta owns the promotion gate and evidence model |
+| Memory | Conversation history | Local repository evidence and a Proof Graph |
+| Learning | Incidental | Changes to Review, Review Again, and saved notes |
+| Provider choice | Commonly coupled to one vendor | Model- and runtime-neutral |
+| Privacy | Often cloud-first | Private per-user storage outside Git |
 
-Automation can avoid interactive prompts with `aperta capture --ai --score 2`.
-Interactive use captures authorship and confidence with one keystroke; confidence
-times out after 15 seconds and Escape leaves it unrated.
+## What you get
 
-## Recommended agent loop
+### Agent work you can review
 
-Wrap the coding agent once and work normally inside it:
+Persistent, multi-turn agent conversations with plans, bounded tools, readable
+activity, syntax-highlighted responses, isolated patches, checks, repair loops,
+and explicit promotion. Read-only requests discard unexpected runtime changes.
 
-```sh
-aperta run --intent "Add passwordless login" -- opencode
-```
+### Universal change capture
 
-Aperta snapshots the repository before and after the agent session, attributes
-only the resulting changes to AI, stores the exact patch as local evidence, and
-refuses to record the same change twice. Existing dirty work is not incorrectly
-included in the session. If you skip the confidence prompt, the change appears
-in the dashboard review queue.
+Aperta observes stable Git-visible changes regardless of whether they came from
+a human, editor, script, or agent. Attribution adds evidence; it is never a
+requirement for review.
 
-For non-interactive agents or scripts:
+### Living Ownership Graph
 
-```sh
-aperta run --intent "Repair CSV export" --score 2 -- your-agent-command --flags
-```
+The graph connects behavior claims to code, tests, runtime observations,
+agent actions, and human defenses. It shows which changes have executable proof,
+which ones an engineer can defend, and which evidence needs another look.
+
+The default view is a short, searchable list of records that need attention.
+Repeated captures roll up into the latest current record instead of filling the
+screen, while the complete append-only revision history remains available.
+
+Each captured change also gets an Ownership Record. The record keeps the
+change, its revision, evidence, open questions, and engineer defense in one place.
 
-## Data
+### Defend each change
 
-Aperta keeps repository identity separate from private developer memory. The
-repository contains only a safe pointer:
+Changes to Review turns a captured change into a risk-ranked summary. Ownership
+reviews ask you to trace the code path, test a failure mode, locate evidence, and
+state what you still do not know. Aperta records your answers. It does not let a
+model certify your understanding.
+
+Project-private review filters can hide path noise from this queue with validated
+regular expressions without removing those files from capture, history, or evidence.
+Completed reviews enter Review Notes and return through Review Again after one,
+three, or seven days. They return sooner when connected code changes.
+
+### Publish what the evidence supports
+
+Download a cited change brief from any Ownership Record. The brief includes the
+captured revision, code and test sources, executable proof, the engineer defense,
+and open questions. A stale record produces a stale brief, so polished writing
+never hides outdated evidence.
+
+### Agent reliability
+
+Agent Reliability measures first-pass verification, repair recovery, tool
+reliability, promotion rate, provider latency, structured error classes, and an
+approximate Trusted Keep Rate. Aperta defects stay separate from model,
+tool, and project failures.
+
+## Models reason. Runtimes execute. Aperta owns trust.
+
+Aperta intentionally separates these responsibilities:
+
+| Layer | Responsibility | Current support |
+| --- | --- | --- |
+| **Model APIs** | Planning, reasoning, explanation, coaching | OpenAI, Anthropic, Google Gemini, DeepSeek, OpenRouter, Groq, Ollama, LM Studio, OpenAI-compatible endpoints |
+| **Agent runtimes** | Repository inspection, edits, and tool execution | Aperta Native, Codex CLI, Claude Code, OpenCode; Cursor is discoverable but structured execution is not yet supported |
+| **Aperta** | Skill selection, capabilities, isolation, verification, promotion, evidence, and learning | Local trust and evidence layer |
+
+Changing the model or runtime never gives it authority to declare its own work
+correct, proven, or understood.
+
+External CLI mechanics are provided by `@vraxis/agent-v`: runtime discovery,
+bounded readiness probes, structured execution, normalized failures, and run
+provenance. Aperta still owns the product-specific safety boundary: skill
+selection, disposable worktrees, checks, evidence, human review, and promotion.
+An installed CLI is not shown as ready until its explicit probe succeeds, and
+every external run records the runtime version and adapter strategy used.
+
+## Private by architecture
+
+The repository stores only a non-sensitive identity pointer:
 
 ```text
 .comprehension/
@@ -312,8 +185,7 @@ repository contains only a safe pointer:
 └── .gitignore
 ```
 
-Raw prompts, agent transcripts, explanations, learning answers, diffs, logs,
-observer state, and the append-only evidence ledger live under:
+Private developer memory lives outside the Git working tree:
 
 ```text
 ~/.aperta/repositories/<project-id>/
@@ -322,65 +194,141 @@ observer state, and the append-only evidence ledger live under:
 └── cache/
 ```
 
-This private directory is outside the Git working tree. Initializing an older
-Aperta repository migrates its existing config, ledger, and cache without
-discarding history. `aperta init` and `aperta doctor` warn when legacy private
-files are still Git-tracked so the developer can commit their deletion and
-audit earlier repository history before sharing it.
-
-The ledger remains append-only and integrity-chained. Each line is one intent,
-diff, confidence, explanation, ownership-evidence, proof, probe, review,
-session-complete, or gate-bypass event. From the Review Queue, an ownership
-session constructs a risk-ranked Change Story, shows the exact diff, collects
-evidence-linked reasoning, and distinguishes demonstrated ownership from a
-self-reported confidence claim without pretending an LLM can grade prose.
-
-Every completed ownership session enters the Learning Journal and leaves the
-immediate review queue, including an honest low-confidence session with evidence
-but no separate prose note. Future session evidence, rating, explanation, and
-completion records are appended as one durable ledger operation.
-
-## Trust Kernel and semantic adapters
-
-Aperta labels every graph claim as Git-observed, structurally inferred,
-compiler-resolved, or runtime-proven. The JDK compiler adapter resolves
-project-local Java symbols and call targets with annotation processing disabled.
-The TypeScript compiler adapter covers JavaScript, TypeScript, JSX/TSX, and the
-script portions of Vue single-file components. Compiler diagnostics downgrade
-semantic coverage to partial instead of hiding missing dependencies or invalid
-project configuration. Other languages retain the universal Git-level workflow
-without invented symbol or call-graph certainty.
-
-## MVP beta workflow
-
-The 1.0 beta separates immediate change review from scheduled retrieval practice
-in **Learn Next**. Completed sessions return after one, three, or seven days
-based on confidence, and return immediately when a later capture touches the
-same files. Proofs and probes run as visible cancelable jobs with a minimized
-environment, bounded output, secret redaction, and explicit disclosure that the
-disposable project copy is not network isolation. A successful Maven proof also
-caches the resolved dependency classpath for deeper subsequent Java analysis.
-
-Ledger writes are serialized across Aperta processes, runtime-validated, and
-integrity-chained. Existing records remain readable as legacy entries. Run
-`aperta doctor` from a tracked repository to check its observer, ledger,
-semantic adapter, and release readiness. The installed CLI runs compiled
-JavaScript; experimental TypeScript execution is used only by the source test
-suite.
-
-## Probe Lab
-
-Aperta turns unproven Impact Graph paths into previewable executable
-probes. A probe is selected by stable ID from Aperta's repository-aware catalog;
-the browser never supplies source code or a command. Aperta copies the project
-into a disposable directory, injects the generated test only there, runs the
-allowlisted test runner, deletes the copy, and retains a bounded result plus a
-hash of the generated source in the local ledger. Proven or disproven probes
-update the graph verdicts. The first executable provider covers Spring Security
-JWT expiry, issuer, and signature validation; endpoint authorization remains
-explicitly blocked until a concrete protected route exists.
-
-Diff evidence and generated probe previews use a safe token renderer with
-language-aware highlighting for Java, TypeScript/JavaScript, JSON, XML, YAML,
-properties, TOML, and shell-like files. Source is rendered as text tokens—not
-injected HTML—so highlighting does not expand the dashboard's trust boundary.
+Raw prompts, transcripts, explanations, learning answers, diffs, logs, and the
+integrity-chained evidence ledger are not team-visible repository files. Model
+credentials never enter project memory. On macOS, keys entered in Model
+Settings are stored in Keychain and are never returned to the browser.
+
+Evidence is sent to a configured provider only for an explicit model action.
+Aperta does not export source, prompts, credentials, or repository evidence to
+an analytics service.
+
+## Safety boundaries
+
+Agent Work has strict safety limits:
+
+- agent edits occur in a disposable Git worktree;
+- ignored files, credential-bearing files, `.git`, and `.comprehension` are blocked;
+- existing files must be read before they can be rewritten;
+- native runs have no arbitrary remote-network tool;
+- project commands come from allowlisted, detected checks;
+- localhost services and HTTP probes have explicit lifecycle controls;
+- output is bounded and common secrets are redacted;
+- failing checks block promotion; and
+- promotion fails if the real repository changed after the run began.
+
+Aperta currently caps a native implementation run at 48 actions, 20 writes,
+300 KB per file, and 1 MB of total writes. These constraints are Aperta policy,
+not suggestions sent to the model.
+
+Read [SECURITY.md](SECURITY.md) before using Aperta with a shared or sensitive
+repository. Report vulnerabilities privately through GitHub Security
+Advisories.
+
+## Language and project support
+
+The universal Git workflow works for any text-based repository. Deeper evidence
+is added only where Aperta has a real adapter:
+
+| Capability | Support |
+| --- | --- |
+| Project checks | Maven, Gradle, npm, pnpm, Yarn, Python, Go, Cargo |
+| Semantic analysis | Java; JavaScript/TypeScript; JSX/TSX; Vue SFC scripts |
+| Safe syntax rendering | Java, JS/TS, JSON, XML, YAML, properties, TOML, shell-like files |
+| Runtime probes | Bounded localhost HTTP and detected local services |
+| Executable Probe Lab | Initial Spring Security JWT behaviors |
+
+Unsupported languages stay useful at the Git, diff, review, ownership, and
+journal layers. Aperta does not claim regex provides compiler-level certainty.
+
+<details>
+<summary><strong>Configure an optional model provider</strong></summary>
+
+The dashboard's **Model Settings** page is the recommended path. Environment
+variables are also supported:
+
+```sh
+# OpenAI
+export OPENAI_API_KEY="..."
+
+# Anthropic
+export APERTA_AI_PROVIDER="anthropic"
+export ANTHROPIC_API_KEY="..."
+export APERTA_AI_MODEL="your-model-id"
+
+# Google Gemini
+export APERTA_AI_PROVIDER="google"
+export GOOGLE_API_KEY="..."
+export APERTA_AI_MODEL="your-model-id"
+
+# DeepSeek, OpenRouter, or Groq
+export APERTA_AI_PROVIDER="deepseek" # or openrouter / groq
+export DEEPSEEK_API_KEY="..."
+export APERTA_AI_MODEL="your-model-id"
+
+# Local Ollama: no API key required
+export APERTA_AI_PROVIDER="ollama"
+export APERTA_AI_MODEL="qwen2.5-coder"
+
+# Any OpenAI-compatible endpoint
+export APERTA_AI_PROVIDER="openai-compatible"
+export APERTA_AI_BASE_URL="https://provider.example/v1"
+export APERTA_AI_MODEL="provider/model-id"
+export APERTA_AI_API_KEY="..."
+```
+
+Remote custom endpoints must use HTTPS. Plain HTTP is accepted only for
+loopback model servers. `APERTA_AI_MODEL` overrides provider defaults.
+
+</details>
+
+<details>
+<summary><strong>Run Aperta from source</strong></summary>
+
+```sh
+git clone https://github.com/Vequan23/aperta.git
+cd aperta
+npm install
+npm test
+npm run build
+npm link
+```
+
+Useful commands:
+
+```sh
+aperta init       # initialize and start observing the current repository
+aperta dashboard  # open the local dashboard
+aperta status     # inspect observer and repository state
+aperta doctor     # validate observer, ledger, adapters, and release readiness
+aperta start      # start the observer explicitly
+aperta stop       # stop the observer
+```
+
+For dashboard development, run `npm run dev`. The standalone Vue marketing site
+lives in `marketing/` and uses the published
+[OSX Components](https://github.com/Vequan23/osx-components) package:
+
+```sh
+npm run dev:marketing
+npm run build:marketing
+```
+
+</details>
+
+## Built for builders who want to remain responsible
+
+Aperta is for developers and teams who want the speed of coding agents
+without surrendering the ability to explain, verify, maintain, and improve the
+software those agents help create.
+
+- Found a bug or rough edge? [Open an issue](https://github.com/Vequan23/aperta/issues).
+- Have an idea for the agent runtime or learning loop? Start a discussion in an issue.
+- Want to contribute? Read [CONTRIBUTING.md](CONTRIBUTING.md) and the
+  [Code of Conduct](CODE_OF_CONDUCT.md).
+- Want to help the project travel? **Star the repository and share the
+  [product site](https://aperta-six.vercel.app/).**
+
+## License
+
+MIT © Aperta contributors. See [LICENSE](LICENSE).