pulse-coding-agent 0.1.0__tar.gz

pulse_coding_agent-0.1.0/.env.example

@@ -0,0 +1,39 @@
+OPENROUTER_API_KEY=replace_me
+GEMINI_API_KEY=replace_me
+OPENAI_API_KEY=replace_me
+
+AGENT_PROVIDER=openrouter
+AGENT_FALLBACK_PROVIDER=gemini
+AGENT_MODEL=qwen/qwen3-coder
+AGENT_MAX_TOKENS=8192
+
+PULSE_MAX_SESSION_TOKENS=100000
+PULSE_MAX_SESSION_COST=1.00
+
+# Google OAuth 2.0 ("Continue with Google")
+# Create credentials at: https://console.cloud.google.com/apis/credentials
+# Application type: Web application
+# Authorized redirect URIs: http://localhost:8080
+GOOGLE_CLIENT_ID=replace_me
+GOOGLE_CLIENT_SECRET=replace_me
+GOOGLE_REDIRECT_URI=http://localhost:8080
+
+# Remote-sandbox client. Uncomment both values to prefer remote execution;
+# local Docker/Podman is the secure fallback when the endpoint is unavailable.
+# PULSE_REMOTE_URL=wss://sandbox.example.com
+# PULSE_REMOTE_TOKEN=replace_with_a_random_32_character_token
+# PULSE_TLS_CERT=/absolute/path/to/client.crt
+# PULSE_TLS_KEY=/absolute/path/to/client.key
+# PULSE_TLS_CA=/absolute/path/to/ca.crt
+
+# Dedicated remote-worker server. Use a random token with at least 32 characters.
+# Non-loopback workers also require all three mTLS paths.
+# PULSE_REMOTE_HOST=127.0.0.1
+# PULSE_REMOTE_PORT=8080
+# PULSE_REMOTE_TOKEN=replace_with_a_random_32_character_token
+# PULSE_REMOTE_WORKSPACE_ROOT=/var/lib/pulse/workspaces
+# PULSE_REMOTE_DB=/var/lib/pulse/executions.sqlite3
+# PULSE_REMOTE_MAX_CONCURRENCY=10
+# PULSE_REMOTE_RETENTION_HOURS=24
+# The worker process uses the same TLS variable names with its server
+# certificate, key, and trusted client CA.

pulse_coding_agent-0.1.0/.gitignore

@@ -0,0 +1,82 @@
+# Secrets and machine-specific configuration
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+*.crt
+*.cer
+credentials.json
+service-account*.json
+secrets*.json
+
+# Python environments, bytecode, and tooling caches
+.venv/
+.audit-wheel-venv*/
+venv/
+env/
+ENV/
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.nox/
+.hypothesis/
+.coverage
+.coverage.*
+htmlcov/
+
+# Python packaging and build output
+build/
+dist/
+*.egg-info/
+*.egg
+pip-wheel-metadata/
+
+# Local data, logs, and editor/OS files
+.agent/logs/
+.agent/repository-index.json
+.agent/provider.json
+.agent/*.sqlite3-shm
+.agent/*.sqlite3-wal
+*.log
+*.sqlite
+*.sqlite3
+*.db
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# JavaScript dependencies (if used by future tooling)
+node_modules/
+
+# Auth session and token files — never commit these
+.agent/.pulse-session.json
+.agent/.pulse-auth-session.json
+.agent/pulse-auth.sqlite3
+
+# Pulse agent workspace default
+.sandbox/
+.pulse/
+
+# Local release/debug artifacts
+coverage.json
+release-metadata/
+fetch_logs.py
+get_logs.py
+gh/
+gh.zip
+patch_tm.py
+pytest_output*.txt
+run_adversarial_audit.py
+run_linux_tests.py
+runs.json
+server_log.txt
+vscode-extension/out/
+vscode-extension/*.vsix

pulse_coding_agent-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,119 @@
+# Pulse Architecture Contract
+
+## Purpose
+
+Pulse is a permissioned coding agent. Its architecture is designed so that a
+model response cannot bypass policy, durable state, verification, or execution
+isolation by importing a convenient lower-level implementation.
+
+## Layer Direction
+
+Dependencies point inward. A layer may depend only on the layer beneath it or
+on a protocol/model owned by a lower layer.
+
+```text
+CLI / RPC
+  -> Orchestration and agent workflow
+    -> Planning, tools, verification, task coordination
+      -> Domain contracts and durable state
+        -> Providers | Sandbox backends | storage adapters | telemetry adapters
+```
+
+### Layer responsibilities
+
+| Layer | Owns | Must not own |
+| --- | --- | --- |
+| CLI and RPC | Input/output, presentation, API compatibility | Policy decisions, direct provider calls, database writes |
+| Orchestration and agent workflow | Prompt lifecycle, plan execution, cancellation propagation | Shell execution, persistence implementation, credential handling |
+| Planning, tools, verification | Typed intent, scoped plans, approval requests, evidence collection | Provider transport and sandbox implementation details |
+| Task coordination | Durable task lifecycle, leases, checkpoints, fencing, recovery | UI behavior and provider-specific reasoning |
+| Sandbox | Policy enforcement, isolated execution, artifacts, execution lifecycle | Agent planning and provider selection |
+| Providers | Model request/response translation and normalized errors | Tool authorization, filesystem access, task lifecycle mutation |
+| Storage and telemetry adapters | Persistence and observation mechanics | Business-policy decisions |
+
+## Domain Contracts
+
+The following contracts are the stable integration points. New behavior must
+extend one of them rather than coupling across layers.
+
+- **Task:** durable user-visible unit of work, identified by `Task.id`.
+- **Lease fence:** `(owner_id, lease_epoch)` capability required to mutate a
+  running task.
+- **Checkpoint:** durable resumable state belonging to a task and step.
+- **Task event:** append-only lifecycle observation for UI, audit, and metrics.
+- **Sandbox execution:** isolated command attempt identified by an execution
+  ID, with policy, result, artifact, and terminal reason.
+- **Remote execution:** remote sandbox attempt with an execution ID persisted
+  against the task before work starts.
+- **Tool call:** typed, policy-authorized operation with validated input and a
+  structured result/error.
+- **Approval:** explicit user authorization linked to the requested action and
+  its scope.
+- **Mutation:** a reversible workspace change with before/after evidence.
+
+## Task Lifecycle Contract
+
+`TaskStatus` is persisted in SQLite and is authoritative after restart.
+
+```text
+PENDING -> QUEUED -> RUNNING -> COMPLETED
+                 |       |  -> FAILED -> QUEUED (bounded retry)
+                 |       |  -> PAUSED -> QUEUED
+                 |       |  -> CANCELLED
+                 |       `-> RECOVERY_PENDING
+                 `-> CANCELLED
+
+RECOVERY_PENDING -> QUEUED | COMPLETED | FAILED
+```
+
+### Lifecycle invariants
+
+1. Only a worker holding the current unexpired lease fence may mutate a
+   `RUNNING` task.
+2. Recovery first persists `RECOVERY_PENDING`; it never retries an ambiguous
+   remote outcome automatically.
+3. A live recorded local owner PID blocks requeue unless that executor
+   acknowledges termination. Absence from another process's in-memory registry
+   is not evidence that the executor stopped.
+4. `COMPLETED`, `FAILED`, and `CANCELLED` clear active ownership. A completed
+   result is immutable except through an explicit new task/retry workflow.
+5. `RemoteTaskExecutor` obtains the attempt ID from `TaskManager` before sandbox
+   submission and passes it as the backend execution ID. Recovery reconciles
+   that exact ID, not a generated replacement.
+
+## Sandbox Lifecycle Contract
+
+Sandbox execution uses the `SandboxExecution` state machine:
+
+```text
+CREATED -> STARTING -> RUNNING -> COMPLETING -> CLEANING -> FINALIZED
+                       |             |
+                       v             v
+                    STOPPING       FAILED -> CLEANING
+                                      |
+                                      v
+                              RECOVERY_REQUIRED
+```
+
+`RECOVERY_REQUIRED` is terminal and requires explicit operator action. Lack of
+an available secure backend, an unenforceable policy, or an unknown external
+outcome must fail closed.
+
+## Dependency Rules Enforced in Tests
+
+- `pulse.core` is domain-only and must not import orchestration, providers,
+  sandbox, CLI/RPC, or persistence implementations.
+- `pulse.providers` must not import agent, orchestration, task-manager, or
+  sandbox modules.
+- `pulse.sandbox` must not import agent, orchestration, planner, or provider
+  modules.
+- `pulse.task_manager` must not import CLI/RPC, agent orchestration, or a
+  provider implementation.
+
+Exceptions require an architecture decision record and an accompanying
+boundary-test update explaining why the dependency is safe.
+
+## Change Checklist
+
+Before merging a behavior change, identify its owning layer, contract,
+lifecycle transition, failure mode, audit signal, and recovery/rollback path.

pulse_coding_agent-0.1.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes are recorded here. Pulse follows Semantic Versioning while
+pre-1.0 APIs may change with release notes and migration guidance.
+
+## [Unreleased]
+
+### Added
+
+- Post-login BYOK onboarding now guides provider and model selection before
+  collecting the selected provider key through hidden terminal input.
+- Provider keys are stored in workspace-scoped native OS credential-vault
+  entries, with safe status, rotation, and removal through `pulse keys`.
+
+### Changed
+
+- Successful key set or rotation migrates that provider away from a legacy
+  plaintext workspace `.env` entry without ever displaying the secret.
+
+## [0.1.0] - 2026-08-29
+
+### Added
+
+- Permissioned local coding-agent CLI with repository intelligence, durable
+  tasks, conversations, mutation tracking, provider routing, and loopback RPC.
+- Docker and authenticated remote sandbox implementations with policy,
+  resource, filesystem, network, secret-redaction, and recovery tests.
+- Configured remote execution is preferred on client machines, with local
+  Docker/Podman used as the secure fallback and no implicit host execution.
+- Production doctor, correlation IDs, remote health/readiness endpoints,
+  operations/security documentation, and explicit deployment boundaries.
+- Reproducible wheel/source builds, artifact-content verification, clean-install
+  smoke tests, cross-platform CI, coverage gate, dependency audit, secret scan,
+  OIDC trusted-publishing workflow, release checksums, source manifest, and
+  CycloneDX SBOM.
+- Direct application dependencies pinned to the versions exercised by the
+  release suite, preventing unreviewed major-version drift at installation.
+- Explicit live-Docker test markers, a single no-skip Docker security gate, and
+  stable Windows pytest teardown behavior in hosted CI.
+- Public `version` and secure provider-key rotation commands, simplified OAuth
+  login/logout UX, authenticated Google userinfo verification, and literal-safe
+  terminal rendering for untrusted text.
+- Non-root Docker overlay export that avoids archive metadata preservation on
+  bind mounts, preventing successful sandbox commands from exiting with 125.
+
+### Known limitations
+
+- The supported release boundary is local and single-user.
+- Hosted tenancy, centralized observability, and independent multi-tenant
+  security validation are outside the supported beta boundary.
+- The VS Code extension is not included in the Python release; it remains
+  source-only and evaluation-only, and its legacy stdio transport is unsupported.

pulse_coding_agent-0.1.0/OPERATIONS.md

@@ -0,0 +1,161 @@
+# Pulse Operations Runbook
+
+## Supported release boundary
+
+Version 0.1.0 is a public beta for local, single-user CLI use. The supported
+artifact is the `pulse-coding-agent` Python distribution and its loopback
+JSON-RPC server. The remote worker is available for controlled evaluation but
+is not approved for multi-tenant or unattended production use.
+
+The VS Code extension is source-only in this release. It compiles in CI but is
+not published, and its legacy stdio client is not a supported transport.
+The loopback JSON-RPC compatibility contract is major version `1`; additive
+methods and fields may be introduced within `1.x`, while removals or semantic
+changes require a new major version. Clients should negotiate with
+`pulse.protocolVersion` and reject incompatible major versions.
+
+## Preflight
+
+From the target project, run:
+
+```text
+pulse doctor --production --target local
+```
+
+Exit code `0` means every blocking local check passed. Exit code `2` means the
+table contains at least one release blocker. Automation should use
+`--json` and inspect the top-level `passed` field.
+
+The loopback JSON-RPC server (`pulse-rpc` or `pulse serve`) requires
+`PULSE_RPC_TOKEN` to be a non-placeholder bearer secret of 32 to 512 characters.
+Start it only on loopback and configure the IDE client to send that bearer token
+in the HTTP authorization header.
+
+For a controlled remote-worker evaluation, configure absolute durable paths,
+a cryptographically random token, and mTLS, then run:
+
+```text
+pulse doctor --production --target remote --json
+pulse-remote --host 0.0.0.0
+```
+
+The remote doctor requires Docker or Podman, a token of at least 32
+non-placeholder characters, an absolute tenant workspace root, an absolute
+SQLite path, bounded concurrency/retention, and all three mTLS files for a
+non-loopback host. `pulse-remote` enforces the same token policy unless
+`--development` is explicitly used on loopback.
+
+## Health and readiness
+
+The remote worker exposes HTTP responses on its WebSocket listener:
+
+- `/healthz` reports process liveness.
+- `/readyz` returns `503` until the Docker worker and durable execution store
+  have initialized, then returns `200`.
+
+On non-loopback deployments the TLS handshake requires a trusted client
+certificate before these endpoints are reachable. Do not expose them directly
+to the public internet.
+
+## State inventory
+
+| State | Default location | Backup requirement |
+| --- | --- | --- |
+| Tasks | `.pulse/tasks.sqlite3` or task-manager store | Back up before upgrade |
+| Conversations and memory | `.agent/*.sqlite3` | Back up before upgrade |
+| Sessions | `.pulse/sessions/` | Back up before upgrade |
+| Mutation/audit/telemetry logs | `.agent/logs/` | Retain according to project policy; logs can contain source snapshots |
+| Remote execution store | `PULSE_REMOTE_DB` | Durable volume and periodic SQLite backup |
+| Remote tenant workspaces | `PULSE_REMOTE_WORKSPACE_ROOT` | Ephemeral; do not treat as the source of record |
+
+Never copy a live SQLite database file without coordinating its WAL. Use the
+bundled online backup operation:
+
+```text
+python -m pulse.storage backup SOURCE.sqlite3 BACKUP.sqlite3
+```
+
+Verify backups with `PRAGMA integrity_check;`, encrypt them, and test restore
+on a separate path. Pulse validates every backup before returning. With all
+Pulse processes stopped, restore using:
+
+```text
+python -m pulse.storage restore BACKUP.sqlite3 SOURCE.sqlite3 --confirm-stopped
+```
+
+Operators still own scheduling, encryption, and retention.
+
+## Upgrade and migration
+
+1. Stop Pulse and remote workers; allow active executions to finish or record
+   them for reconciliation.
+2. Back up every store in the state inventory and record the running Pulse
+   version and artifact SHA-256.
+3. Install the new wheel into a new environment; do not overwrite the known
+   good environment.
+4. Run `pulse doctor --production`, then the artifact entry-point smoke tests.
+5. Start one canary workspace. Confirm health/readiness, task recovery, audit
+   output, and provider access before broader rollout.
+
+Every supported SQLite store records `PRAGMA user_version`. Migrations run in
+an immediate transaction, create an online pre-migration backup for an existing
+schema, reject databases newer than the running binary, and roll back on an
+error. Task schema is v3, remote execution is v2, and conversation, episodic,
+and long-term memory stores are v1.
+
+Pulse is an application distribution, so its direct runtime dependencies are
+pinned to the versions exercised by CI and recorded in the release SBOM.
+Upgrades to those pins require a new Pulse release and the complete release
+gate; do not loosen them in a production environment.
+
+## Rollback
+
+1. Stop the failing process. Do not automatically replay executions with an
+   unknown external outcome.
+2. Reinstall the previous wheel by exact version or SHA-256-verified artifact.
+3. Restore the pre-upgrade database backup only if the older version cannot
+   read the migrated store. Preserve the failed database for investigation.
+4. Restart on loopback, run the production doctor, and reconcile
+   `RECOVERY_PENDING` or remote `UNKNOWN` executions manually.
+
+PyPI releases are immutable. A bad public release must be yanked, not replaced;
+publish a new patch version after verification.
+
+## Credential rotation
+
+1. Generate a new random remote token and distribute it through the secret
+   manager, never through Git or command-line history.
+2. During a bounded overlap window, configure old and new tokens as a
+   comma-separated set, restart the worker, and move clients to the new token.
+3. Remove the old token and restart again. Check redacted audit logs for failed
+   uses of the retired credential.
+4. Rotate mTLS certificates and provider/OAuth credentials at their issuers if
+   exposure is possible.
+
+## Incident response
+
+Contain the worker, revoke credentials, preserve the execution database and
+redacted logs, and quarantine ambiguous tasks. Do not paste raw model output,
+source snapshots, access tokens, or tenant artifacts into tickets. Record the
+release SHA, correlation ID, task ID, remote execution ID, and mutation
+transaction ID. See `SECURITY.md` and `src/pulse/sandbox/SECURITY.md` for the
+threat boundary.
+
+## Release procedure
+
+1. Update `CHANGELOG.md`; make version values agree in `pyproject.toml` and
+   `pulse.__version__`.
+2. Run the full local release verification and push the commits.
+3. Wait for required CI checks on the release commit, including live Docker
+   security tests.
+4. Confirm the protected `public-beta` and `pypi` environments, provider secret,
+   and PyPI trusted-publisher mapping are configured.
+5. Push tag `vX.Y.Z`. Do not manually create the GitHub Release.
+6. The protected tag workflow rebuilds and verifies the source, runs the live
+   provider and no-skip Docker security gates, publishes to PyPI through OIDC,
+   then creates the GitHub Release. It attaches SHA-256 checksums, a
+   source-bound manifest, evaluation evidence, and a CycloneDX SBOM.
+
+The `public-beta` environment requires `OPENAI_API_KEY` and may set
+`PULSE_E2E_MODEL`. The `pypi` environment must match the trusted publisher for
+`.github/workflows/release.yml`.

pulse_coding_agent-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.5
+Name: pulse-coding-agent
+Version: 0.1.0
+Summary: Permissioned coding-agent CLI with durable planning and isolated execution.
+Project-URL: Homepage, https://github.com/Roastedpotato21/pulse
+Project-URL: Repository, https://github.com/Roastedpotato21/pulse
+Project-URL: Issues, https://github.com/Roastedpotato21/pulse/issues
+Project-URL: Changelog, https://github.com/Roastedpotato21/pulse/blob/master/CHANGELOG.md
+Project-URL: Security, https://github.com/Roastedpotato21/pulse/security/policy
+Keywords: ai,coding-agent,developer-tools,sandbox
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: <3.14,>=3.11
+Requires-Dist: httpx==0.28.1
+Requires-Dist: keyring==25.7.0
+Requires-Dist: openai==2.44.0
+Requires-Dist: prompt-toolkit==3.0.52
+Requires-Dist: python-dotenv==1.2.2
+Requires-Dist: rich==15.0.0
+Requires-Dist: typer==0.26.8
+Requires-Dist: websockets==16.1
+Description-Content-Type: text/markdown
+
+# Pulse
+
+Pulse is a permissioned coding-agent CLI for working on software repositories.
+It combines repository-aware planning, durable task state, explicit mutation
+controls, sandboxed command execution, provider routing, audit trails, and cost
+tracking in one Python package.
+
+> **Public beta — 0.1.0:** Pulse is supported for controlled, local,
+> single-user use. The remote worker and VS Code extension are included for
+> evaluation and development, but they are not supported as multi-tenant or
+> unattended production services.
+
+## Requirements
+
+- Python 3.11, 3.12, or 3.13
+- An API key for the model provider you choose
+- Docker or Podman for local isolated execution, or access to a configured
+  Pulse remote worker
+
+## Install
+
+Install the first beta from PyPI:
+
+```bash
+uv tool install pulse-coding-agent==0.1.0
+```
+
+Alternatively, use `pipx install pulse-coding-agent==0.1.0` or install it in a
+dedicated virtual environment with `pip`.
+
+## Quick start
+
+Run these commands from the repository you want Pulse to work on:
+
+```bash
+pulse login
+pulse doctor --production --target local
+pulse ask "Explain this repository and identify the highest-risk missing test"
+```
+
+After Google login, Pulse guides provider selection, model selection, and hidden
+BYOK entry. New provider keys are stored in the native OS credential vault.
+Credentials can also be supplied through environment variables such as `OPENAI_API_KEY`,
+`ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, or `OPENROUTER_API_KEY`. Do not commit a
+populated `.env` file.
+
+To run commands without installing Docker on the client workstation, configure
+a remote worker:
+
+```text
+PULSE_REMOTE_URL=wss://sandbox.example.com
+PULSE_REMOTE_TOKEN=<random token of at least 32 characters>
+PULSE_TLS_CERT=/absolute/path/to/client.crt
+PULSE_TLS_KEY=/absolute/path/to/client.key
+PULSE_TLS_CA=/absolute/path/to/ca.crt
+```
+
+When those variables are set, Pulse tries the remote sandbox first and uses a
+local Docker/Podman engine only as a secure fallback. The remote worker host
+still requires Docker or Podman; execution never silently falls back to the
+client host.
+
+Before allowing mutations or shell execution, review the proposed operation and
+its permission prompt. Treat model output, tool arguments, and repository
+content as untrusted input.
+
+## What the beta includes
+
+- Repository indexing and context-aware conversations
+- Durable plans, tasks, sessions, episodic memory, and recovery state
+- Permission-gated file mutations with transactional rollback
+- Host, Docker, Podman, and authenticated remote sandbox backends
+- Filesystem, network, resource, timeout, and secret-redaction policies
+- Multi-provider model routing and usage/cost accounting
+- Loopback JSON-RPC integration through `pulse-rpc` or `pulse serve`
+- Production preflight checks, structured audit events, and correlation IDs
+
+The package installs three entry points:
+
+```text
+pulse          Interactive CLI
+pulse-rpc      Loopback JSON-RPC server
+pulse-remote   Evaluation-only remote sandbox worker
+```
+
+Use `pulse --help` for the current command surface and command-specific help.
+`pulse-rpc` and `pulse serve` require a strong `PULSE_RPC_TOKEN` bearer secret
+and must stay bound to loopback.
+
+### Interactive shell
+
+Run `pulse` without arguments for the responsive project shell. Natural-language
+input goes to the agent; prefix any regular CLI command with `/` to run it in the
+same session, such as `/status`, `/keys list`, or `/chat switch ID`. Completions
+appear as you type and are always generated from the public CLI parser.
+
+- `Tab` or `Ctrl-Space`: open/accept command completion
+- `Up`/`Down`: navigate history; `Ctrl-R`: search history
+- `Alt-Enter`: insert a newline; `Enter`: submit
+- `Ctrl-C`: clear the current input; on an empty prompt, exit
+- `/help`, `/clear`, and `/exit`: shell controls
+
+History is stored locally in the Git-ignored `.pulse/history` file.
+
+### Account and provider keys
+
+```bash
+pulse version
+pulse login
+pulse auth-status
+pulse whoami
+pulse logout
+pulse keys
+pulse keys list
+pulse keys set openai
+pulse keys rotate openai
+pulse keys remove openai
+```
+
+`pulse keys` opens the status and rotation manager. Set and rotate operations
+prompt with hidden input; provider keys are never accepted as command-line
+arguments or printed back to the terminal. New keys are stored in a
+workspace-scoped entry in the native OS credential vault. Existing `.env` keys
+remain readable for compatibility and are removed for that provider after a
+successful vault-backed set or rotation. Environment variables and external
+secret managers remain supported as fallback sources.
+
+## Supported boundary
+
+The 0.1.0 beta supports the local CLI and loopback RPC server for one trusted
+user on one workstation. Pulse does not claim a security boundary between
+mutually untrusted tenants. Do not expose `pulse-rpc` or `pulse-remote` directly
+to the public internet.
+
+The remote worker requires authenticated transport, durable configuration, and
+container isolation. It remains evaluation-only until tenant isolation,
+centralized observability, load testing, disaster-recovery exercises, and an
+independent security review are complete. The VS Code extension is source-only
+and is not part of the Python distribution.
+
+Pulse sends prompts and selected repository context to the configured model
+provider. Data handling therefore also depends on that provider's terms and
+settings. Pulse itself does not include product analytics or telemetry export
+in this beta.
+
+## Development
+
+Clone the repository and create the locked development environment:
+
+```bash
+uv sync --locked
+uv run pulse --help
+```
+
+Run the local quality gates:
+
+```bash
+uv run ruff check src tests scripts
+uv run mypy
+uv run pytest tests/ -k "not sandbox" --cov=pulse --cov-report=term-missing --cov-fail-under=54
+uv build
+uv run python scripts/verify_release_artifacts.py dist --expected-version 0.1.0
+```
+
+Docker security tests require a working Docker daemon and are enforced by the
+hosted release workflow. See [OPERATIONS.md](OPERATIONS.md) for release and
+rollback procedures.
+
+## Documentation
+
+- [Architecture](ARCHITECTURE.md)
+- [Operations and releases](OPERATIONS.md)
+- [Security policy](SECURITY.md)
+- [Sandbox security boundary](src/pulse/sandbox/SECURITY.md)
+- [Privacy policy](PRIVACY.md)
+- [Changelog](CHANGELOG.md)
+
+To report a vulnerability, use GitHub private vulnerability reporting instead
+of a public issue. General defects and beta feedback belong in the
+[issue tracker](https://github.com/Roastedpotato21/pulse/issues).