opendevops 0.1.1__tar.gz

opendevops-0.1.1/.env.example

@@ -0,0 +1,22 @@
+# Image used by docker-compose. Release bundles pin this to their exact version.
+LANGGRAPH_IMAGE=ghcr.io/skundu42/opendevops:latest
+
+# Required for service mode. Empty values deliberately make Compose refuse to start.
+POSTGRES_PASSWORD=
+GATEWAY_TOKEN=
+GRAFANA_ADMIN_PASSWORD=
+ANTHROPIC_API_KEY=
+LANGSMITH_API_KEY=
+
+# Local-development dashboard authentication. Use OIDC in production.
+DASHBOARD_TOKEN=
+
+# Production dashboard OIDC settings.
+OIDC_CLIENT_ID=
+OIDC_CLIENT_SECRET=
+
+# Optional OTLP/HTTP endpoint.
+OTEL_EXPORTER_OTLP_ENDPOINT=
+
+# Optional LangSmith tracing. Leave false to disable application traces.
+LANGSMITH_TRACING=false

opendevops-0.1.1/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+.venv/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+/audit/
+/state/*.sqlite3*
+*.egg-info/
+dist/
+node_modules/
+src/opendevops/interfaces/dashboard_assets/generated/
+.superpowers/
+.coverage

opendevops-0.1.1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

opendevops-0.1.1/PKG-INFO

@@ -0,0 +1,385 @@
+Metadata-Version: 2.4
+Name: opendevops
+Version: 0.1.1
+Summary: Autonomous DevOps agent: policy-gated, budget-capped, audit-chained operations on Kubernetes, GitHub, cloud CLIs, and SSH
+Project-URL: Homepage, https://github.com/skundu42/opendevops
+Project-URL: Repository, https://github.com/skundu42/opendevops
+Project-URL: Issues, https://github.com/skundu42/opendevops/issues
+Author: Sandipan Kundu
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent,automation,devops,kubernetes,langchain,langgraph,llm,sre
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: <4.0,>=3.11
+Requires-Dist: deepagents==0.6.12
+Requires-Dist: langchain-anthropic<2,>=1.4.7
+Requires-Dist: langchain==1.3.14
+Requires-Dist: langgraph==1.2.9
+Requires-Dist: pydantic-settings>=2.6
+Requires-Dist: pyyaml>=6
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.15
+Provides-Extra: checkpoint
+Requires-Dist: aiosqlite; extra == 'checkpoint'
+Requires-Dist: langgraph-checkpoint-sqlite; extra == 'checkpoint'
+Provides-Extra: dev
+Requires-Dist: agentevals==0.0.9; extra == 'dev'
+Requires-Dist: fakeredis<3,>=2.31; extra == 'dev'
+Requires-Dist: langgraph-cli[inmem]==0.4.31; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: server
+Requires-Dist: authlib<2,>=1.6; extra == 'server'
+Requires-Dist: fastapi; extra == 'server'
+Requires-Dist: httpx<1,>=0.27; extra == 'server'
+Requires-Dist: langgraph-sdk<0.5,>=0.4; extra == 'server'
+Requires-Dist: opentelemetry-api<2,>=1.30; extra == 'server'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.30; extra == 'server'
+Requires-Dist: opentelemetry-sdk<2,>=1.30; extra == 'server'
+Requires-Dist: prometheus-client; extra == 'server'
+Requires-Dist: redis>=5; extra == 'server'
+Requires-Dist: sse-starlette; extra == 'server'
+Provides-Extra: slack
+Requires-Dist: aiohttp; extra == 'slack'
+Requires-Dist: apscheduler<4,>=3.10; extra == 'slack'
+Requires-Dist: slack-bolt==1.30.0; extra == 'slack'
+Provides-Extra: ssh
+Requires-Dist: asyncssh==2.24.0; extra == 'ssh'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/assets/opendevops-mark.png" width="148" alt="opendevops logo">
+</p>
+
+<h1 align="center">opendevops</h1>
+
+<p align="center">
+  <strong>An autonomous DevOps agent with a smaller blast radius than its prompt.</strong>
+</p>
+
+<p align="center">
+  Investigate infrastructure, diagnose incidents, and perform tightly scoped operations through
+  argv-only execution, least-privilege credentials, fail-closed policy, budget stop-losses, and
+  structurally verifiable audit chains.
+</p>
+
+<p align="center">
+  <a href="https://github.com/skundu42/opendevops/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/skundu42/opendevops/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/skundu42/opendevops/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/skundu42/opendevops?display_name=tag&sort=semver"></a>
+  <a href="LICENSE"><img alt="Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-28516b.svg"></a>
+  <img alt="Python 3.11 and 3.12" src="https://img.shields.io/badge/python-3.11%20%7C%203.12-28a6a1.svg">
+  <img alt="Project status: beta" src="https://img.shields.io/badge/status-beta-f0643b.svg">
+</p>
+
+---
+
+## What is opendevops?
+
+opendevops is an open-source operations agent built on LangGraph and LangChain deepagents. It can
+trace a CrashLoop, analyze CI failures, inspect cloud resources, verify drift, summarize noisy
+logs, and execute a deliberately narrow set of staging remediations.
+
+The model never receives a shell. Every command is an `argv: list[str]` request that passes through
+budget controls, a default-deny policy engine, a credential-selection boundary, output scrubbing,
+and a per-run audit chain.
+
+```text
+you › why is pod api-0 in namespace web crash-looping?
+→ run_command kubectl -n web describe pod api-0
+→ run_command kubectl -n web logs api-0 --previous --tail 200
+
+The container was OOMKilled (exit 137). Its JVM heap is configured above the
+container memory limit. Reduce the heap or raise the workload limit.
+
+spent $0.0841 (run) / $0.34 (today)
+```
+
+### Capabilities
+
+| Area | Supported today | Boundary |
+|---|---|---|
+| Kubernetes | diagnostics, logs, events, Helm inspection, controlled apply/rollout/scale | production rw requires an active expiring grant, server dry-run, independent approval and rw kubeconfig |
+| GitHub | CI diagnosis, run inspection, PR-based remediation | repository and API method/path allowlists |
+| AWS | curated EC2, ECS, RDS, CloudFormation, S3, Lambda, CloudWatch and related reads | no cloud-resource deployment or IAM access |
+| Google Cloud | curated Compute, GKE, Cloud SQL, Pub/Sub, Logging, Storage, Run and Functions reads | mutations and secret access denied |
+| Azure | curated VM, AKS, ACR, networking, SQL, Cosmos DB, Monitor and resource reads | mutations and secret material denied |
+| Remote hosts | structured, read-only SSH checks | pinned user, key, hosts and `known_hosts` |
+| Interfaces | CLI, HTTP, Slack, scheduler, Alertmanager and GitHub webhooks | one shared gateway and safety core |
+| Operations UI | identity-scoped agent chat, live runs, approvals, policy/cost/audit detail and capability grants | OIDC RBAC + CSRF; chat never exposes raw tool arguments, output, or credential values |
+
+> [!IMPORTANT]
+> This is not a general AWS, Google Cloud, or Azure deployment engine. Terraform, Pulumi,
+> CloudFormation updates, Google Cloud Deploy, ARM/Bicep deployment, and unrestricted provider CLI
+> mutations are not enabled.
+
+## Operations dashboard
+
+The service-mode dashboard includes an authenticated command channel for asking the agent directly
+about connected infrastructure. Conversations are private to the exact OIDC issuer and subject;
+operator/admin turns stream over SSE, retain a bounded transcript, and use the same gateway,
+budgets, policy, capability grants, and approval path as every other interface. The chat shows
+assistant responses and sanitized lifecycle activity, never raw command arguments or tool output.
+
+The rest of the dashboard merges verified audit chains with live gateway telemetry. It shows active
+runs, queues, workers, pending approvals, per-model timing and cost progression, policy decisions,
+tool timing, correlation IDs, spend, SLIs, and audit integrity. Operators can cancel runs;
+approvers can resolve interruptions; admins can activate or revoke typed capability grants.
+
+<p align="center">
+  <img src="docs/assets/dashboard.png" alt="Authenticated opendevops operations dashboard showing run activity, policy events, costs, audit integrity, and recent runs">
+</p>
+
+Production authentication is generic OpenID Connect (Entra ID, Google Workspace, Okta, Keycloak,
+or another standards-compliant issuer). Groups/roles map to `viewer`, `operator`, `approver`, and
+`admin`. Browser cookies contain only an opaque random session handle; session state and OIDC
+transactions are stored server-side, support immediate revocation, and expire within eight hours.
+Every control action records the OIDC issuer and subject. Static-token login remains available only
+as the explicit local-development mode.
+
+```yaml
+server:
+  dashboard_auth_mode: oidc
+  dashboard_session_backend: redis
+  dashboard_session_redis_url: redis://redis:6379/2
+  dashboard_cookie_secure: true
+  dashboard_chat_enabled: true
+  dashboard_chat_retention_days: 30
+  dashboard_chat_max_message_chars: 8000
+  oidc:
+    issuer: https://id.example.com/realms/operations
+    client_id_env: OIDC_CLIENT_ID
+    client_secret_env: OIDC_CLIENT_SECRET
+    redirect_uri: https://ops.example.com/dashboard/oidc/callback
+    roles_claim: groups
+    role_mappings:
+      viewer: [devops-readers]
+      operator: [devops-operators]
+      approver: [change-approvers]
+      admin: [devops-admins]
+```
+
+```sh
+docker compose up -d
+open http://localhost:8123/dashboard
+```
+
+For production, register the callback exactly, terminate TLS before Caddy, use Redis sessions, and
+keep requester and approver group membership operationally separate. See
+[deployment](guides/deployment.md#operator-dashboard).
+
+## Guarded dangerous actions
+
+Dangerous capabilities are versioned state, not free-form dashboard YAML. An operator proposes a
+specific environment, capability, explicit target set, reason, lifetime, execution count,
+per-run/repeat limit, failure threshold, cooldown, and mandatory dry-run. An approver approves it;
+an admin activates it. Production rejects requester self-approval, and the executor atomically
+consumes the grant before each rw action.
+
+```sh
+opendevops config propose-grant \
+  --environment prod \
+  --capability kubernetes_deploy \
+  --target kind-prod/web \
+  --reason "Deploy reviewed release 2026.07.26"
+
+opendevops config approve-grant <proposal-id> --actor change-approver
+opendevops config activate-grant <proposal-id> --actor platform-admin
+opendevops config grants
+```
+
+The control plane is an additional gate: a grant never overrides a policy deny, credential scope,
+target allowlist, or dry-run requirement. AWS, GCP, and Azure policy packs remain read-only until
+reviewed deployment commands and distinct rw credentials are added. Production Kubernetes
+execution also requires `targets.kubernetes.kubeconfig_rw_by_environment.prod`; the legacy
+`kubeconfig_rw` field is accepted only as a staging fallback.
+
+## Why the execution model is different
+
+```mermaid
+flowchart LR
+    I["CLI · API · Slack · Scheduler · Webhooks · OIDC dashboard chat"] --> G["AgentGateway"]
+    O["OIDC session + RBAC"] --> I
+    G --> B["Budgets and call limits"]
+    B --> P["Fail-closed policy"]
+    P -->|allow / rewrite| E["argv-only executor"]
+    P -->|escalate| H["Human decision"]
+    P -->|deny| D["Refusal"]
+    E --> C["One scoped credential"]
+    X["Expiring capability grant + loop limits"] --> P
+    H --> X
+    C --> T["Kubernetes · GitHub · Cloud CLIs · SSH"]
+    P --> A["Audit chain"]
+    E --> A
+    B --> A
+    A --> U["Authenticated dashboard"]
+    A --> W["WORM / SIEM sink"]
+```
+
+- **No shell surface.** Commands execute with `shell=False`; interpreters and command-building
+  utilities are denied.
+- **Credentials are the hard boundary.** The executor constructs a fresh environment and injects
+  exactly one credential family for the winning rule and channel.
+- **Policy fails closed.** Unknown tools, commands, flags, contexts, identities, and policy errors
+  deny execution.
+- **Secrets stay out of argv.** Standalone `{{secret:NAME}}` declarations inject environment
+  variables for env-aware programs and are removed before execution; embedded expansion is denied.
+- **Outputs are scrubbed first.** Known token forms and high-entropy strings are redacted before
+  model context, virtual files, or audit excerpts.
+- **USD limits are stop-losses.** Call, tool, recursion, and wall-clock limits are hard controls;
+  cost is known after model calls and can overshoot by in-flight work.
+- **Audit claims are precise.** Local SHA-256 chains prove structural consistency. Authenticity
+  requires the independently protected WORM or INSERT-only sink used in production.
+
+Read the full [security model](guides/security-model.md) before connecting real infrastructure.
+
+## Quick start
+
+### Prerequisites
+
+- Python 3.11 or 3.12
+- [`uv`](https://docs.astral.sh/uv/)
+- `kubectl` and access to a cluster where you can create the agent ServiceAccount
+- an Anthropic API key
+- optional provider CLIs only for integrations you enable
+
+### Install and configure
+
+```sh
+# Install the prebuilt universal wheel; no repository clone or frontend build is needed.
+uv tool install \
+  'opendevops[checkpoint,ssh] @ https://github.com/skundu42/opendevops/releases/download/v0.1.1/opendevops-0.1.1-py3-none-any.whl'
+
+mkdir opendevops-workspace
+opendevops init opendevops-workspace
+cd opendevops-workspace
+cp .env.example .env
+# Set ANTHROPIC_API_KEY in .env.
+
+# Provision a read-only, secrets-denied Kubernetes identity.
+kubectl apply -f ops/k8s/agent-view-rbac.yaml
+ops/k8s/gen-kubeconfig.sh <your-context>
+
+# Add <your-context> to targets.kubernetes.allowed_contexts in config/config.yaml.
+opendevops config check
+opendevops chat
+```
+
+The generated workspace deliberately has an empty Kubernetes context allowlist. `config check`
+and every runtime entry point refuse to proceed until you make that deployment choice explicitly.
+`opendevops init` also refuses to replace an existing workspace unless `--force` is explicit.
+
+Continue with the [step-by-step getting-started guide](guides/getting-started.md).
+
+## Configuration
+
+Configuration is strict Pydantic over three files:
+
+| File | Purpose |
+|---|---|
+| [`config/config.yaml`](config/config.yaml) | targets, credential variable names, execution, interfaces and service settings |
+| [`config/models.yaml`](config/models.yaml) | agent model aliases and cache-aware pricing |
+| [`config/budgets.yaml`](config/budgets.yaml) | per-run profiles, daily stop-losses and counter backend |
+| [`config/policy/`](config/policy) | base denies, environment overlays and capability packs |
+
+Unknown keys fail validation. Missing credentials for an enabled policy family fail agent
+construction. Secret values belong in the process environment, never YAML.
+
+See the complete [configuration reference](guides/configuration.md).
+
+## Service mode
+
+The included Compose stack runs the LangGraph Server, Postgres, Redis, Caddy, Vector, Prometheus,
+Grafana, and the authenticated dashboard:
+
+```sh
+curl -fLO \
+  https://github.com/skundu42/opendevops/releases/download/v0.1.1/opendevops-deploy-0.1.1.tar.gz
+tar -xzf opendevops-deploy-0.1.1.tar.gz
+cd opendevops-0.1.1
+cp .env.example .env
+# Fill every required blank in .env.
+
+docker compose config -q
+docker compose pull
+docker compose up -d
+```
+
+The release bundle is pinned to `ghcr.io/skundu42/opendevops:0.1.1`; published images support
+`linux/amd64` and `linux/arm64`. Neither Node.js nor an application source build is required. The
+image intentionally contains the application runtime rather than every cloud vendor CLI; install
+only the `kubectl`, `helm`, `gh`, `aws`, `gcloud`, or `az` binaries for policy families you enable
+in a derived runtime image or credential-isolated executor. A missing binary fails closed.
+
+Security-sensitive Compose credentials have no default values. Caddy is the only ingress; server
+APIs and metrics require `GATEWAY_TOKEN`, native webhook routes retain their HMAC/bearer
+authentication, and `/dashboard/*` uses the application session described above.
+
+> [!WARNING]
+> Never run the service stack on a Kubernetes cluster the agent itself manages. Use a dedicated
+> operations VM or a separate operations cluster.
+
+See [deployment](guides/deployment.md) for TLS, shared counters, audit shipping, alerts, backups,
+quota planning, and go-live gates.
+
+## CLI
+
+| Command | Purpose |
+|---|---|
+| `opendevops init [directory]` | scaffold config and Kubernetes bootstrap files from the wheel |
+| `opendevops chat` | streaming REPL with environment, profile and principal selection |
+| `opendevops config check` | validate runtime-critical configuration |
+| `opendevops config grants` | list the control-plane revision and capability proposals |
+| `opendevops config propose-grant` | propose a typed, expiring dangerous capability |
+| `opendevops config approve-grant` | approve a proposal (requester separation in prod) |
+| `opendevops config activate-grant` / `revoke-grant` | activate or immediately revoke a grant |
+| `opendevops audit verify --dir <dir>` | strictly verify audit structure and completion |
+| `opendevops audit verify --allow-incomplete` | diagnose structurally valid crashed/in-progress runs |
+| `opendevops version` | print the installed version |
+
+## Documentation
+
+| Guide | Contents |
+|---|---|
+| [Getting started](guides/getting-started.md) | first installation and live session |
+| [Architecture](guides/architecture.md) | graph, middleware, gateways, execution and data flow |
+| [Configuration](guides/configuration.md) | every supported setting |
+| [Policy](guides/policy.md) | rule schema, packs, precedence and extension |
+| [Security model](guides/security-model.md) | trust boundaries, failure modes and residual risk |
+| [Budgets](guides/budgets.md) | call limits, timeouts, pricing and USD stop-losses |
+| [Audit](guides/audit.md) | event schema, verification, shipping and authenticity |
+| [Interfaces](guides/interfaces.md) | CLI, dashboard, HTTP, webhooks, Slack and scheduler |
+| [Deployment](guides/deployment.md) | service stack, monitoring and production gates |
+| [Development](guides/development.md) | tests, conventions and extension points |
+| [Upgrade notes](docs/UPGRADE.md) | dependency and migration guidance |
+| [Release process](RELEASING.md) | versioning, artifacts, signing and PyPI trusted publishing |
+
+## Development
+
+```sh
+npm ci
+npm run frontend:check
+npm run frontend:build
+
+uv sync --extra checkpoint --extra server --extra slack --extra ssh --extra dev
+
+uv run pytest -q
+uv run ruff check .
+uv run mypy src ops
+uv lock --check
+```
+
+Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the
+[development guide](guides/development.md). Please report vulnerabilities privately according to
+[SECURITY.md](SECURITY.md).
+
+## License
+
+Licensed under the [Apache License 2.0](LICENSE).