opendots 0.2.0__tar.gz

opendots-0.2.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# OpenDots 0.2.0
+
+This release develops the local prototype with a prompt-first terminal client,
+safer proposal handling, packaged setup, and runtime maintenance.
+
+- Exact-action approvals bind check commands, workspace content and owner policy.
+- Write scopes reject symlink bypasses and protect owner validation harnesses.
+- Failed checks can trigger bounded repair; completion requires current evidence.
+- Complete binary-capable Git patches are retained without preview truncation.
+- Completed proposals require explicit acceptance before future tasks use them.
+- Source synchronization creates new snapshots while preserving old proposals.
+- Prompt-first terminal UI supports reviews, history, activity, cancellation,
+  proposal acceptance, command completion and input editing.
+- Packaged `init`, `doctor`, Bash installation and user systemd lifecycle commands.
+- Non-root Docker deployment initializes persistent configuration on first run.
+- Durable daily invocation budgets, queue limits, priority aging and source health.
+- Bounded connector polling, poisoned-line quarantine, gap reporting and deduplication.
+- Explicitly enabled package extensions and typed custom tool arguments.
+- Offline backup, verified restore, and preview-first workspace retention.
+- CI covers Python 3.11–3.13, installed wheels, Bubblewrap and container lifecycle.
+
+## Upgrade notes
+
+Back up runtime data before upgrading and install into a new environment. Stop
+old services before switching their executable to the new environment.
+
+Existing `latest_branch` metadata does not automatically become an accepted
+base. Review the relevant completed proposal and explicitly accept its commit.
+Omitted `write_paths` in JSON configuration now grants no write access. Default
+protected paths include `check.py`, `tests/**` and `.github/**`; review your scopes
+and checks when migrating. Shipped demo configurations now require validation.
+
+A draft GitHub release contains the wheel, source archive, installer and SHA-256
+checksums after validation. Publishing the draft is a maintainer action. Packages
+are not automatically published to PyPI. OpenDots remains a local alpha; live
+Codex behavior and stronger deployment boundaries require separate validation.

opendots-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shashank Shekhar Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opendots-0.2.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md LICENSE NOTICE CHANGELOG.md install.sh
+recursive-include examples *.json *.jsonl *.py *.md *.jsx
+recursive-include deploy *.sh *.example
+recursive-include docs *.md

opendots-0.2.0/NOTICE

@@ -0,0 +1,5 @@
+OpenDots includes source previously distributed under the name Spots.
+Original source notice: Copyright (c) 2026 Spots contributors.
+That source was distributed under the MIT license. The permission and warranty
+terms are reproduced in LICENSE. The repository owner's existing LICENSE has
+been preserved without modification.

opendots-0.2.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: opendots
+Version: 0.2.0
+Summary: Event-driven agents with persistent targets and reviewable local actions
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Shashankss1205/OpenDots
+Project-URL: Repository, https://github.com/Shashankss1205/OpenDots
+Project-URL: Issues, https://github.com/Shashankss1205/OpenDots/issues
+Project-URL: Documentation, https://github.com/Shashankss1205/OpenDots/tree/main/docs
+Keywords: agents,automation,terminal,event-driven
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# OpenDots
+
+![OpenDots architecture: your goal and incoming events drive planning, permitted actions, checks, and changes for your review.](https://raw.githubusercontent.com/Shashankss1205/OpenDots/main/assets/opendots-overview.svg)
+
+**Give an agent your goal. Connect the information it needs. Review the work it proposes.**
+
+OpenDots runs on your computer and coordinates CLI agents, cloud models or local Ollama models around a goal you choose. It listens for incoming information, keeps task history and notes, and can check progress on a schedule. You choose the project, allowed changes, checks, and approval rules.
+
+A **heartbeat** is a scheduled check-in. An **event** is a message from you or a connected tool. A **target** is one configured agent with its own goal. The **runtime** is the process you leave running.
+
+## What can it do?
+
+- Pursue your saved goal using Claude Code, Codex, OpenAI, Anthropic, compatible APIs or Ollama.
+- React to terminal requests, local HTTP messages, JSONL files, and GitHub activity.
+- Assess matching events against each goal, with a visible confidence estimate and reason.
+- Revisit progress on a configurable heartbeat schedule.
+- Read project files, propose scoped edits, and run checks you configure.
+- Ask for approval, retain local patches, and preserve history across restarts.
+- Send [notifications](https://github.com/Shashankss1205/OpenDots/blob/main/docs/NOTIFICATIONS.md) to local files or configured webhooks, including Slack/Discord formats.
+- Manage multiple agents through a terminal or a local web interface.
+- Extend providers, tools and polling or persistent event listeners through a [shared plugin framework](https://github.com/Shashankss1205/OpenDots/blob/main/docs/PLUGINS.md).
+
+This is a local prototype. It does not automatically publish PRs, deploy applications, or pull upstream changes. Model access comes from your provider account. Checks prove only what you configure them to test.
+
+Inspect loaded integrations with `opendots plugins`, `/plugins` in the TUI, or **Loaded plugins** in the web interface. Connection status appears under `/listeners`. Slack and Discord require a connector plugin or an external bridge; they are not bundled integrations.
+
+## What you need
+
+- **Linux, Python 3.11+, Git, and Bubblewrap** with working namespaces for isolated checks.
+- **Model access**: a signed-in Claude Code/Codex CLI, an API key, or a running Ollama server with a model. See [provider setup](https://github.com/Shashankss1205/OpenDots/blob/main/docs/PROVIDERS.md).
+- **Your own project directory and a goal** you want the agent to pursue.
+
+On Ubuntu/Debian, install prerequisites with `sudo apt-get install python3 python3-venv git bubblewrap curl`. Check `python3 --version` is at least 3.11. Docker and a GitHub token are not needed to start.
+
+## Install OpenDots
+
+Choose **one** method.
+
+### Option A: install from PyPI
+
+With [pipx](https://pipx.pypa.io/stable/installation/) installed:
+
+```bash
+pipx install opendots
+pipx ensurepath
+```
+
+Alternatively, install in a Python virtual environment with `python -m pip install opendots`.
+
+### Option B: download and run the installer
+
+```bash
+curl -fsSLo install-opendots.sh https://raw.githubusercontent.com/Shashankss1205/OpenDots/main/install.sh
+bash install-opendots.sh
+```
+
+The script installs into a separate Python environment without sudo. Follow its printed PATH instruction; with the default location:
+
+```bash
+export PATH="$HOME/.local/share/opendots/runtime/bin:$PATH"
+```
+
+Add that line to your shell startup file for new terminals. `--prefix DIR` chooses a different installation directory; `--ref COMMIT` pins a reviewed revision. Existing installations are not overwritten.
+
+### Option C: install the Python package from GitHub
+
+With [pipx](https://pipx.pypa.io/stable/installation/) installed:
+
+```bash
+pipx install 'git+https://github.com/Shashankss1205/OpenDots.git'
+pipx ensurepath
+```
+
+Open a new terminal if pipx asks you to. All methods provide the `opendots` command.
+
+## Start with your project and your goal
+
+### 1. Create your configuration
+
+First sign in to your chosen CLI (`claude auth login`, or `codex login`). From your project's directory, replace the goal text below with your own objective:
+
+```bash
+opendots init --workspace "$PWD" --goal "Describe what you want this agent to achieve" --backend claude
+```
+
+Use `--backend codex` if that is your provider. For OpenAI, Anthropic, compatible APIs or Ollama, follow the [model setup commands](https://github.com/Shashankss1205/OpenDots/blob/main/docs/PROVIDERS.md#direct-apis-and-local-models). No sample project, predefined repair, or demo event is created.
+
+The command prints your configuration path. By default it is `~/.config/opendots/config.json` (or under `XDG_CONFIG_HOME`). Open that file to review your saved goal and settings. Normal setup starts with **reads and notes allowed, no writable paths, no configured checks, model goal-relevance assessment enabled, and no heartbeat**. Before enabling changes, set `write_paths`, `checks`, and `required_checks` for your project.
+
+Want periodic work? Add `--heartbeat 1800` to `init` for a 30-minute check-in. A heartbeat can start work immediately when the runtime starts, and uses your provider's allowance. You can also configure schedules later.
+
+### 2. Check the setup, then start the runtime
+
+```bash
+opendots doctor
+opendots serve
+```
+
+Continue only when `doctor` reports top-level `"ok": true`. It checks configuration, executables, authentication, and isolation; it is not proof of a completed live model task. Leave the `serve` terminal open.
+
+If you used `init --directory DIR`, pass the printed path explicitly: `opendots --config DIR/config.json doctor` and `opendots --config DIR/config.json serve`. Configuration and runtime data must stay outside your project directory.
+
+### 3. Open an interface
+
+In another terminal:
+
+```bash
+opendots
+```
+
+Or open **http://127.0.0.1:8765** on the same machine. Both interfaces use the same runtime.
+
+## Talk to your agent
+
+Type these commands inside the OpenDots terminal interface, not your shell:
+
+```text
+/agents
+/use project
+```
+
+Then type a normal message about your goal. It becomes an `owner.request` event for the selected agent. The agent can investigate, save notes, or explain a blocker. It cannot write until you configure allowed paths and approve the proposed action.
+
+| Command | What it does |
+| --- | --- |
+| `/listeners` | See configured sources, subscriptions, schedules, and relevance settings. |
+| `/notifications` | See notification destinations and delivery status. |
+| `/plugins` | Inspect loaded plugins, versions, and the capabilities each owns. |
+| `/events` / `/event ID` | Browse received events and inspect payloads, routing reasons, and confidence. |
+| `/send TYPE MESSAGE` | Create a message with your chosen event type. |
+| `/connect` | Learn how to connect an event producer. |
+| `/providers` | Show models, provider profiles and agent assignments. |
+| `/status` | Show the provider, source health, and model usage. |
+| `/activity` | See what is happening. |
+| `/reviews` | Find work waiting for approval. |
+| `/review ID` | Inspect the action for the task number shown. |
+| `/approve ID` | Request approval; type the requested confirmation to permit that exact action. |
+| `/work ID` | Inspect task results and check evidence. |
+| `/proposal ID` | Inspect a completed patch and its acceptance command. |
+| `/pause` / `/resume` | Stop or resume the selected agent taking new work. |
+| `/help` | Show all commands. |
+
+Accepting a completed proposal makes its commit the base of future tasks; it does not change your original checkout or push code. Pause the agent and finish or cancel active work before acceptance. Editing your saved goal or subscriptions requires restarting the runtime.
+
+`/quit` or Ctrl+D disconnects the interface. **Ctrl+C in the `serve` terminal stops the runtime.** Pausing does not cancel active work or stop incoming messages from queuing.
+
+## Connect incoming information
+
+Use `/listeners` and `/events` in the terminal, or **What is listening?** and **Received events** in the web interface. The web form can preview and send arbitrary JSON payloads.
+
+A **source** brings messages into OpenDots. A **subscription** specifies which message types an agent listens to. Setting up one without the other does not create useful work.
+
+| Method | How information arrives |
+| --- | --- |
+| Terminal / web form | You submit a message. |
+| HTTP | Your tool sends a JSON event to `POST /api/events`. |
+| JSONL | Your tool appends one JSON object per line to a watched inbox. |
+| GitHub polling | OpenDots periodically fetches new repository activity. |
+| GitHub webhook | A separately configured receiver forwards signed deliveries. |
+| Heartbeat | OpenDots emits a scheduled event while running. |
+
+**[Create events and connect sources](https://github.com/Shashankss1205/OpenDots/blob/main/docs/EVENTS.md)** explains each setup with producer commands, subscription rules, and how confidence controls execution. New setups assess matching events before actions; uncertain decisions block work for inspection. Confidence is a model estimate, not a calibrated probability.
+
+Native Slack, email, Kafka, Redis, and arbitrary filesystem-watch adapters are not built in. External tools can bridge into HTTP or JSONL. GitHub activity does not automatically refresh the agent's source-code snapshot.
+
+## Documentation
+
+- [Notifications](https://github.com/Shashankss1205/OpenDots/blob/main/docs/NOTIFICATIONS.md): configure alerts, webhooks, retries and delivery history.
+
+- [Plugins](https://github.com/Shashankss1205/OpenDots/blob/main/docs/PLUGINS.md): install packages and build providers, tools, polling adapters or persistent listeners.
+- [Events and listeners](https://github.com/Shashankss1205/OpenDots/blob/main/docs/EVENTS.md): create messages, connect tools, inspect history and relevance.
+- [Provider setup](https://github.com/Shashankss1205/OpenDots/blob/main/docs/PROVIDERS.md): CLI authentication, API keys, local models and per-agent model profiles.
+- [Implementation](https://github.com/Shashankss1205/OpenDots/blob/main/docs/IMPLEMENTATION.md): configuration, policies, event routing, and storage.
+- [Development and operations](https://github.com/Shashankss1205/OpenDots/blob/main/docs/DEVELOPMENT.md): checks, packaging, services, backup, and source refresh.
+- [Validation](https://github.com/Shashankss1205/OpenDots/blob/main/docs/VALIDATION.md): tested behavior and remaining live-provider validation.
+- [Roadmap](https://github.com/Shashankss1205/OpenDots/blob/main/docs/ROADMAP.md) and [Contributing](https://github.com/Shashankss1205/OpenDots/blob/main/CONTRIBUTING.md).
+
+<details>
+<summary>Show me a demo or a worked sample</summary>
+
+Demos are optional and separate from normal setup. For deterministic fixtures:
+
+```bash
+opendots init --demo --directory "$HOME/.config/opendots-demo"
+opendots --config "$HOME/.config/opendots-demo/config.json" serve --port 8766
+```
+
+Open http://127.0.0.1:8766 and explicitly select the five-event demo. It uses no model and makes no changes to a real cluster or upstream repository.
+
+For a fully worked real-provider sample using OpenDots' own source, see [the optional goal walkthrough](https://github.com/Shashankss1205/OpenDots/blob/main/docs/GOALS_AND_EVENTS.md). Its predefined goal and syntax check are illustrative; they are not applied to your project by normal setup.
+
+</details>
+
+OpenDots is an independent experiment inspired by OpenAI's Dots idea. MIT licensed; see [LICENSE](https://github.com/Shashankss1205/OpenDots/blob/main/LICENSE) and [NOTICE](https://github.com/Shashankss1205/OpenDots/blob/main/NOTICE).

opendots-0.2.0/README.md

@@ -0,0 +1,194 @@
+# OpenDots
+
+![OpenDots architecture: your goal and incoming events drive planning, permitted actions, checks, and changes for your review.](https://raw.githubusercontent.com/Shashankss1205/OpenDots/main/assets/opendots-overview.svg)
+
+**Give an agent your goal. Connect the information it needs. Review the work it proposes.**
+
+OpenDots runs on your computer and coordinates CLI agents, cloud models or local Ollama models around a goal you choose. It listens for incoming information, keeps task history and notes, and can check progress on a schedule. You choose the project, allowed changes, checks, and approval rules.
+
+A **heartbeat** is a scheduled check-in. An **event** is a message from you or a connected tool. A **target** is one configured agent with its own goal. The **runtime** is the process you leave running.
+
+## What can it do?
+
+- Pursue your saved goal using Claude Code, Codex, OpenAI, Anthropic, compatible APIs or Ollama.
+- React to terminal requests, local HTTP messages, JSONL files, and GitHub activity.
+- Assess matching events against each goal, with a visible confidence estimate and reason.
+- Revisit progress on a configurable heartbeat schedule.
+- Read project files, propose scoped edits, and run checks you configure.
+- Ask for approval, retain local patches, and preserve history across restarts.
+- Send [notifications](https://github.com/Shashankss1205/OpenDots/blob/main/docs/NOTIFICATIONS.md) to local files or configured webhooks, including Slack/Discord formats.
+- Manage multiple agents through a terminal or a local web interface.
+- Extend providers, tools and polling or persistent event listeners through a [shared plugin framework](https://github.com/Shashankss1205/OpenDots/blob/main/docs/PLUGINS.md).
+
+This is a local prototype. It does not automatically publish PRs, deploy applications, or pull upstream changes. Model access comes from your provider account. Checks prove only what you configure them to test.
+
+Inspect loaded integrations with `opendots plugins`, `/plugins` in the TUI, or **Loaded plugins** in the web interface. Connection status appears under `/listeners`. Slack and Discord require a connector plugin or an external bridge; they are not bundled integrations.
+
+## What you need
+
+- **Linux, Python 3.11+, Git, and Bubblewrap** with working namespaces for isolated checks.
+- **Model access**: a signed-in Claude Code/Codex CLI, an API key, or a running Ollama server with a model. See [provider setup](https://github.com/Shashankss1205/OpenDots/blob/main/docs/PROVIDERS.md).
+- **Your own project directory and a goal** you want the agent to pursue.
+
+On Ubuntu/Debian, install prerequisites with `sudo apt-get install python3 python3-venv git bubblewrap curl`. Check `python3 --version` is at least 3.11. Docker and a GitHub token are not needed to start.
+
+## Install OpenDots
+
+Choose **one** method.
+
+### Option A: install from PyPI
+
+With [pipx](https://pipx.pypa.io/stable/installation/) installed:
+
+```bash
+pipx install opendots
+pipx ensurepath
+```
+
+Alternatively, install in a Python virtual environment with `python -m pip install opendots`.
+
+### Option B: download and run the installer
+
+```bash
+curl -fsSLo install-opendots.sh https://raw.githubusercontent.com/Shashankss1205/OpenDots/main/install.sh
+bash install-opendots.sh
+```
+
+The script installs into a separate Python environment without sudo. Follow its printed PATH instruction; with the default location:
+
+```bash
+export PATH="$HOME/.local/share/opendots/runtime/bin:$PATH"
+```
+
+Add that line to your shell startup file for new terminals. `--prefix DIR` chooses a different installation directory; `--ref COMMIT` pins a reviewed revision. Existing installations are not overwritten.
+
+### Option C: install the Python package from GitHub
+
+With [pipx](https://pipx.pypa.io/stable/installation/) installed:
+
+```bash
+pipx install 'git+https://github.com/Shashankss1205/OpenDots.git'
+pipx ensurepath
+```
+
+Open a new terminal if pipx asks you to. All methods provide the `opendots` command.
+
+## Start with your project and your goal
+
+### 1. Create your configuration
+
+First sign in to your chosen CLI (`claude auth login`, or `codex login`). From your project's directory, replace the goal text below with your own objective:
+
+```bash
+opendots init --workspace "$PWD" --goal "Describe what you want this agent to achieve" --backend claude
+```
+
+Use `--backend codex` if that is your provider. For OpenAI, Anthropic, compatible APIs or Ollama, follow the [model setup commands](https://github.com/Shashankss1205/OpenDots/blob/main/docs/PROVIDERS.md#direct-apis-and-local-models). No sample project, predefined repair, or demo event is created.
+
+The command prints your configuration path. By default it is `~/.config/opendots/config.json` (or under `XDG_CONFIG_HOME`). Open that file to review your saved goal and settings. Normal setup starts with **reads and notes allowed, no writable paths, no configured checks, model goal-relevance assessment enabled, and no heartbeat**. Before enabling changes, set `write_paths`, `checks`, and `required_checks` for your project.
+
+Want periodic work? Add `--heartbeat 1800` to `init` for a 30-minute check-in. A heartbeat can start work immediately when the runtime starts, and uses your provider's allowance. You can also configure schedules later.
+
+### 2. Check the setup, then start the runtime
+
+```bash
+opendots doctor
+opendots serve
+```
+
+Continue only when `doctor` reports top-level `"ok": true`. It checks configuration, executables, authentication, and isolation; it is not proof of a completed live model task. Leave the `serve` terminal open.
+
+If you used `init --directory DIR`, pass the printed path explicitly: `opendots --config DIR/config.json doctor` and `opendots --config DIR/config.json serve`. Configuration and runtime data must stay outside your project directory.
+
+### 3. Open an interface
+
+In another terminal:
+
+```bash
+opendots
+```
+
+Or open **http://127.0.0.1:8765** on the same machine. Both interfaces use the same runtime.
+
+## Talk to your agent
+
+Type these commands inside the OpenDots terminal interface, not your shell:
+
+```text
+/agents
+/use project
+```
+
+Then type a normal message about your goal. It becomes an `owner.request` event for the selected agent. The agent can investigate, save notes, or explain a blocker. It cannot write until you configure allowed paths and approve the proposed action.
+
+| Command | What it does |
+| --- | --- |
+| `/listeners` | See configured sources, subscriptions, schedules, and relevance settings. |
+| `/notifications` | See notification destinations and delivery status. |
+| `/plugins` | Inspect loaded plugins, versions, and the capabilities each owns. |
+| `/events` / `/event ID` | Browse received events and inspect payloads, routing reasons, and confidence. |
+| `/send TYPE MESSAGE` | Create a message with your chosen event type. |
+| `/connect` | Learn how to connect an event producer. |
+| `/providers` | Show models, provider profiles and agent assignments. |
+| `/status` | Show the provider, source health, and model usage. |
+| `/activity` | See what is happening. |
+| `/reviews` | Find work waiting for approval. |
+| `/review ID` | Inspect the action for the task number shown. |
+| `/approve ID` | Request approval; type the requested confirmation to permit that exact action. |
+| `/work ID` | Inspect task results and check evidence. |
+| `/proposal ID` | Inspect a completed patch and its acceptance command. |
+| `/pause` / `/resume` | Stop or resume the selected agent taking new work. |
+| `/help` | Show all commands. |
+
+Accepting a completed proposal makes its commit the base of future tasks; it does not change your original checkout or push code. Pause the agent and finish or cancel active work before acceptance. Editing your saved goal or subscriptions requires restarting the runtime.
+
+`/quit` or Ctrl+D disconnects the interface. **Ctrl+C in the `serve` terminal stops the runtime.** Pausing does not cancel active work or stop incoming messages from queuing.
+
+## Connect incoming information
+
+Use `/listeners` and `/events` in the terminal, or **What is listening?** and **Received events** in the web interface. The web form can preview and send arbitrary JSON payloads.
+
+A **source** brings messages into OpenDots. A **subscription** specifies which message types an agent listens to. Setting up one without the other does not create useful work.
+
+| Method | How information arrives |
+| --- | --- |
+| Terminal / web form | You submit a message. |
+| HTTP | Your tool sends a JSON event to `POST /api/events`. |
+| JSONL | Your tool appends one JSON object per line to a watched inbox. |
+| GitHub polling | OpenDots periodically fetches new repository activity. |
+| GitHub webhook | A separately configured receiver forwards signed deliveries. |
+| Heartbeat | OpenDots emits a scheduled event while running. |
+
+**[Create events and connect sources](https://github.com/Shashankss1205/OpenDots/blob/main/docs/EVENTS.md)** explains each setup with producer commands, subscription rules, and how confidence controls execution. New setups assess matching events before actions; uncertain decisions block work for inspection. Confidence is a model estimate, not a calibrated probability.
+
+Native Slack, email, Kafka, Redis, and arbitrary filesystem-watch adapters are not built in. External tools can bridge into HTTP or JSONL. GitHub activity does not automatically refresh the agent's source-code snapshot.
+
+## Documentation
+
+- [Notifications](https://github.com/Shashankss1205/OpenDots/blob/main/docs/NOTIFICATIONS.md): configure alerts, webhooks, retries and delivery history.
+
+- [Plugins](https://github.com/Shashankss1205/OpenDots/blob/main/docs/PLUGINS.md): install packages and build providers, tools, polling adapters or persistent listeners.
+- [Events and listeners](https://github.com/Shashankss1205/OpenDots/blob/main/docs/EVENTS.md): create messages, connect tools, inspect history and relevance.
+- [Provider setup](https://github.com/Shashankss1205/OpenDots/blob/main/docs/PROVIDERS.md): CLI authentication, API keys, local models and per-agent model profiles.
+- [Implementation](https://github.com/Shashankss1205/OpenDots/blob/main/docs/IMPLEMENTATION.md): configuration, policies, event routing, and storage.
+- [Development and operations](https://github.com/Shashankss1205/OpenDots/blob/main/docs/DEVELOPMENT.md): checks, packaging, services, backup, and source refresh.
+- [Validation](https://github.com/Shashankss1205/OpenDots/blob/main/docs/VALIDATION.md): tested behavior and remaining live-provider validation.
+- [Roadmap](https://github.com/Shashankss1205/OpenDots/blob/main/docs/ROADMAP.md) and [Contributing](https://github.com/Shashankss1205/OpenDots/blob/main/CONTRIBUTING.md).
+
+<details>
+<summary>Show me a demo or a worked sample</summary>
+
+Demos are optional and separate from normal setup. For deterministic fixtures:
+
+```bash
+opendots init --demo --directory "$HOME/.config/opendots-demo"
+opendots --config "$HOME/.config/opendots-demo/config.json" serve --port 8766
+```
+
+Open http://127.0.0.1:8766 and explicitly select the five-event demo. It uses no model and makes no changes to a real cluster or upstream repository.
+
+For a fully worked real-provider sample using OpenDots' own source, see [the optional goal walkthrough](https://github.com/Shashankss1205/OpenDots/blob/main/docs/GOALS_AND_EVENTS.md). Its predefined goal and syntax check are illustrative; they are not applied to your project by normal setup.
+
+</details>
+
+OpenDots is an independent experiment inspired by OpenAI's Dots idea. MIT licensed; see [LICENSE](https://github.com/Shashankss1205/OpenDots/blob/main/LICENSE) and [NOTICE](https://github.com/Shashankss1205/OpenDots/blob/main/NOTICE).

opendots-0.2.0/deploy/docker-entrypoint.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+set -eu
+runtime_config="${OPENDOTS_CONFIG:-/data/config.json}"
+if [ ! -f "$runtime_config" ]; then
+  if [ "$runtime_config" != /data/config.json ]; then
+    echo "Configured file is missing: $runtime_config" >&2
+    exit 1
+  fi
+  if [ "${OPENDOTS_DEMO:-0}" = 1 ]; then
+    opendots init --demo --directory /data
+  else
+    echo 'Mount your real config and set OPENDOTS_CONFIG. Optional fixtures require OPENDOTS_DEMO=1.' >&2
+    exit 1
+  fi
+fi
+exec opendots --config "$runtime_config" "$@"

opendots-0.2.0/deploy/opendots.service.example

@@ -0,0 +1,16 @@
+[Unit]
+Description=OpenDots local event-driven agent runtime
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=/absolute/path/to/opendots
+ExecStart=/usr/bin/python3 -m opendots --config /absolute/path/to/your/config.json serve
+Restart=on-failure
+RestartSec=5
+TimeoutStopSec=240
+Environment=PYTHONDONTWRITEBYTECODE=1
+
+[Install]
+WantedBy=default.target