forgeo-cli 0.3.0__tar.gz

forgeo_cli-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,116 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - "v*"
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: pip install -e ".[dev]"
+      - name: Lint with ruff
+        run: ruff check src tests
+      - name: Type check with mypy
+        run: python -m mypy src/forgeo
+      - name: Test with pytest
+        run: python -m pytest
+
+  build-binaries:
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            asset: forgeo-linux-amd64
+            binary: dist/forgeo
+          - os: macos-15-intel
+            asset: forgeo-darwin-amd64
+            binary: dist/forgeo
+          - os: macos-latest
+            asset: forgeo-darwin-arm64
+            binary: dist/forgeo
+          - os: windows-latest
+            asset: forgeo-windows-amd64.exe
+            binary: dist/forgeo.exe
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install package and PyInstaller
+        run: python -m pip install --upgrade pip pyinstaller .
+      - name: Build standalone binary
+        run: pyinstaller forgeo.spec
+      - name: Rename binary to release asset name
+        shell: bash
+        run: |
+          mkdir -p release-assets
+          cp "${{ matrix.binary }}" "release-assets/${{ matrix.asset }}"
+      - name: Upload binary artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.asset }}
+          path: release-assets/${{ matrix.asset }}
+          if-no-files-found: error
+
+  release:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build-binaries
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install build
+        run: python -m pip install --upgrade build
+      - name: Build wheel and sdist
+        run: python -m build
+      - name: Download binary artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: binaries
+          merge-multiple: true
+      - name: Publish GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+            binaries/*
+
+  publish-pypi:
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build wheel and sdist
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

forgeo_cli-0.3.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+
+# Forgeo runtime artifacts
+.forgeo/
+BLOCKER.md
+forgeo.log
+*.lock
+forgeo.yaml
+
+# Tooling
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+.idea/
+
+# Docs build output
+site/
+
+# Build artifacts
+build/
+dist/
+
+# AI assistant context
+CONTEXT.md
+
+# Local deploy script (server-specific paths)
+scripts/deploy-docs.sh

forgeo_cli-0.3.0/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `forgeo web [--host HOST] [--port PORT]` — a standalone central dashboard
+  (default `0.0.0.0:8790`, foreground like `forgeo start`) that aggregates
+  every registered instance. It reads each instance's data straight from its
+  files (`backlog.json`, `runs.jsonl`, `forgeo.log`, `BLOCKER.md`), so it
+  works whether or not that instance's daemon is running. Home page at `/`,
+  per-instance pages at `/instances/<name>/` (kanban backlog plus logs,
+  runs, blocker and config tabs), and a per-instance API under
+  `/api/instances/<name>/`.
+- Shared web-server helpers (`forgeo.web_common`) used by the central
+  dashboard.
+- Task editing in the web console: the task detail modal gained an **Edit**
+  mode (Save/Cancel), backed by a new `PATCH
+  /api/instances/<name>/tasks/<id>` endpoint and `JSONBacklog.update_task`.
+
+### Changed
+
+- **The embedded per-daemon web server is gone.** `forgeo start` no longer
+  binds any port (`web_host`/`web_port` config keys are removed). The daemon
+  instead writes its live state (pid, started at, last outcome, next run) to
+  `daemon.state.json` next to the backlog after every cycle.
+- The central dashboard (`forgeo web`) is now the **only** web interface:
+  it reads the daemon state files for accurate status, and it gained the
+  instance backlog's write endpoints, `POST
+  /api/instances/<name>/tasks` (with the web form on each instance page) and
+  `PATCH /api/instances/<name>/tasks/<id>`, so no feature was lost.
+- `forgeo.web_common` docstring/API updated; `forgeo.server` module
+  removed.
+
+## [0.2.1] - 2026-08-05
+
+### Added
+
+- `web_host` config option: the web dashboard/API bind address. Default
+  `127.0.0.1` (unchanged behavior); set `0.0.0.0` to reach it from other
+  hosts on the local network.
+- `install.sh` now prefers a prebuilt standalone binary downloaded from the
+  matching GitHub Release for the host OS/arch — **no Python required**.
+  The pipx/pip fallback remains, used only when no prebuilt binary matches
+  the platform and a Python >= 3.11 is available.
+- Tag-triggered CI builds single-file executables with PyInstaller on
+  Linux (amd64), macOS (amd64/arm64), and Windows (amd64) and attaches them
+  to the GitHub Release (`forgeo.spec`).
+- Installer tests cover the binary-download path and the pipx/pip fallback
+  with stubs (no network).
+
+## [0.2.0] - 2026-08-04
+
+### Added
+
+- `CHANGELOG.md` in Keep a Changelog format, with the `0.1.0` history
+  backfilled.
+- Tag-triggered CI job that builds the wheel and sdist and attaches them to a
+  GitHub Release.
+- Release steps documented in `CONTRIBUTING.md`.
+- Web console frontend in `src/forgeo/web/`: a self-contained
+  HTML/CSS/JS dashboard (no framework, no build step, no external assets)
+  served at `/` showing the backlog grouped by status and daemon status,
+  auto-refreshing every 30 seconds.
+- `install.sh` is now hosted on the project's own server and served from
+  <https://forgeo.org/install.sh>; README and docs use it in the one-liner.
+
+## [0.1.0] - 2026-08-03
+
+Initial release of the scheduled, agent-driven software forgeo.
+
+### Added
+
+- `forgeo start` persistent daemon: every `interval_minutes` it picks the
+  oldest `OPEN` task, runs it through the configured agent command, and commits
+  and pushes the result directly on `main`.
+- Refactoring mode: when the backlog is empty, runs the agent with the
+  configured `refactor_prompt`.
+- Blocker flow: an agent exiting with `blocked_exit_code` commits partial work,
+  writes `BLOCKER.md`, and pauses Forgeo until the task is reopened.
+- Guided first-time setup: `forgeo init` wizard.
+- `forgeo once` command to run a single cycle and exit.
+- `forgeo status`, `forgeo stop`, and `forgeo restart` commands.
+- `--auto` flag for the agent command for unattended runs.
+- Local web dashboard and HTTP API served by the daemon.
+- Durable run history recorded to `runs.jsonl` and exposed through the API.
+- Telegram notification when a task is marked `BLOCKED`.
+- Curl-to-bash one-liner installer (`install.sh`), pipx-first.
+- MkDocs documentation website, published at <https://forgeo.org/>.
+- GitHub Actions CI running `pytest`, `ruff`, and `mypy` on Python 3.11-3.13.
+- Optional Docker sandbox for agent execution.
+- Per-task `agent_command` override for cheap/expensive model routing.
+- Project renamed to Forgeo, with MIT `LICENSE` and `CONTRIBUTING.md`.
+
+### Changed
+
+- Project slimmed down to a single-purpose scheduled worker; the interactive
+  backlog generator utility was removed.
+- Duplicated commit/blocker handling unified between task and refactor runs.
+- Agent stdout/stderr streamed into run logs instead of buffered.
+- Corrupt backlog files preserved instead of silently discarded.
+- Git command timeout made configurable; agent timeout made optional with
+  overlapping-run skipping.
+- Dogfooding docs removed; local configs kept out of the repository.
+
+[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/lucaGazzola/forgeo/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/lucaGazzola/forgeo/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/lucaGazzola/forgeo/releases/tag/v0.1.0

forgeo_cli-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,120 @@
+# Contributing to Forgeo
+
+Thanks for contributing! This project is an agent-driven software forgeo.
+
+## Development setup
+
+Requires Python 3.11+.
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+`.[dev]` installs the package plus the toolchain: `pytest`, `ruff`, and
+`mypy`.
+
+## Quality gates
+
+Run all three before opening a PR. CI enforces the same gates.
+
+```bash
+pytest           # the test suite (tests/)
+ruff check       # linting (src, tests)
+mypy src/forgeo # type checking
+```
+
+The full suite should pass and `ruff check` and `mypy src/forgeo` should be
+clean.
+
+## Writing a backlog task
+
+Backlog tasks are how Forgeo receives work. Tasks are JSON objects
+in the backlog file (see [docs/backlog.md](docs/backlog.md) for the full
+schema). A good task has three things:
+
+- **`id`** — a unique identifier, e.g. `TASK-001`. Duplicate ids are rejected.
+- **`description`** — a self-contained specification handed to the agent. State
+  the current behavior, the desired behavior, and where the change lives. The
+  agent does not have your mental context, so spell it out.
+- **`acceptance_criteria`** — a list of concrete, verifiable outcomes. The
+  forgeo renders these into the agent's `FORGEO_TASK` instruction, so write
+  them as checks the agent can confirm itself (e.g. "`pytest` passes", "the
+  `--help` output lists `once`").
+
+Example:
+
+```json
+{
+  "id": "TASK-002",
+  "title": "Add `forgeo once` command to run a single cycle",
+  "description": "The CLI only offers `forgeo start` (the persistent daemon). Add a `once` subcommand that runs exactly one cycle and exits.",
+  "acceptance_criteria": [
+    "`forgeo once --config forgeo.yaml` runs one cycle and exits 0",
+    "`forgeo --help` lists `once`",
+    "Tests cover the new command"
+  ],
+  "status": "OPEN",
+  "created_at": "2026-07-31T20:01:00Z"
+}
+```
+
+Keep the description scoped to one task, keep acceptance criteria minimal and
+testable, and never commit the backlog file — it is gitignored.
+
+## Pull-request process
+
+Human contributions use the normal GitHub flow:
+
+1. Create a feature branch off `main`: `git checkout -b feat/my-change`.
+2. Make your change and commit it with a concise, descriptive message.
+3. Run the [quality gates](#quality-gates) and fix any failures.
+4. Push the branch and open a pull request against `main`.
+5. CI runs `pytest`, `ruff check`, and `mypy src/forgeo` on the PR — it must
+   be green.
+6. Address review feedback; keep the branch rebased on `main` if it drifts.
+7. Once approved and green, merge. Follow-up work is welcome as a new PR or as
+   a backlog task for Forgeo.
+
+## Releasing
+
+Releases are cut from `main` and published as GitHub Releases. Tagging the
+repo triggers CI, which builds the wheel, sdist, **and prebuilt standalone
+binaries** and attaches them to the release — there is no PyPI publishing yet,
+and `install.sh` downloads the matching prebuilt binary from the release
+(`pipx`/`pip` fallback only when no binary matches the platform).
+
+> Patch and minor releases **must** include the built binaries, otherwise the
+> `install.sh` binary path (the default, no-Python install) breaks. The CI
+> `build-binaries` job builds them automatically on any `v*` tag, but make
+> sure the release actually carries them — the `forgeo-<os>-<arch>` assets
+> listed below are what the installer downloads.
+
+1. Confirm the [quality gates](#quality-gates) are green on `main`.
+2. Bump the version in `pyproject.toml` (`version = "x.y.z"`) and in
+   `src/forgeo/__init__.py`, following
+   [Semantic Versioning](https://semver.org/).
+3. Update the `VERSION=` at the top of `install.sh` to the new `x.y.z` so the
+   installer downloads the new release's binaries.
+4. Update `CHANGELOG.md`: move the entries from `## [Unreleased]` under a new
+   `## [x.y.z] - <date>` section, add the compare links at the bottom, and
+   leave a fresh `## [Unreleased]` heading.
+5. Commit the bump and changelog update, e.g. `git commit -m "Release x.y.z"`.
+6. Tag and push the tag — the `build-binaries` and `release` jobs in
+   `.github/workflows/ci.yml` build the wheel, sdist, and PyInstaller binaries
+   for Linux (amd64), macOS (amd64/arm64), and Windows (amd64) and attach them
+   to a GitHub Release:
+
+   ```bash
+   git tag vx.y.z
+   git push origin vx.y.z
+   ```
+
+7. Confirm the release and its artifacts (wheel, sdist, and the
+   `forgeo-linux-amd64`, `forgeo-darwin-amd64`, `forgeo-darwin-arm64`,
+   `forgeo-windows-amd64.exe` binaries) are listed under
+   <https://github.com/lucaGazzola/forgeo/releases>.
+
+## License
+
+This project is MIT-licensed; see [LICENSE](LICENSE).

forgeo_cli-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Software Forgeo Contributors
+
+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.

forgeo_cli-0.3.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: forgeo-cli
+Version: 0.3.0
+Summary: A scheduled software forgeo: executes backlog tasks on main, refactors when idle, and writes BLOCKER.md when it needs human input.
+Project-URL: Homepage, https://forgeo.org
+Project-URL: Documentation, https://forgeo.org
+Project-URL: Repository, https://github.com/lucaGazzola/forgeo
+Project-URL: Issues, https://github.com/lucaGazzola/forgeo/issues
+Author: Forgeo Contributors
+License: MIT License
+        
+        Copyright (c) 2026 Software Forgeo Contributors
+        
+        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.
+License-File: LICENSE
+Keywords: agents,ai,automation,backlog,orchestration,scheduler
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="docs/img/logo.png" alt="Forgeo logo" width="128">
+</div>
+
+<div align="center">
+  <img src="docs/img/title.svg" alt="Forgeo" width="128">
+</div>
+
+
+[![CI](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml/badge.svg)](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Forgeo is an autonomous software forgeo for people with ideas, not teams.**
+You have a product idea — an app, a website, an internal automation — but no
+developers on staff. With Forgeo you don't need any: you write down what needs
+to be built as a simple list of tasks, and an AI coding agent works through the
+list on its own, writing the code and committing it to your repository. No
+branches, no pull requests, no developer to hire.
+
+All you need is basic comfort with a terminal, a git repository, and any coding
+agent CLI — Claude Code, aider, opencode, or your own script. Forgeo works with
+all of them.
+
+Forgeo decides what to do next on its own: while tasks are left it implements
+the oldest one and commits the result, and when the backlog is empty it reviews
+the codebase and cleans it up. It only interrupts you when a decision is
+genuinely yours to make — everything else happens autonomously.
+
+## Quickstart
+
+Requires a git repository (no Python needed — the one-liner downloads a
+prebuilt binary for your OS, or `pipx install forgeo-cli` works too). The full
+walkthrough is in [Getting started](docs/getting-started.md).
+
+```bash
+# 1. Install
+curl -fsSL https://forgeo.org/install.sh | bash
+
+# 2. Create your Forgeo (guided wizard, run from your project root)
+forgeo init
+
+# 3. Start Forgeo
+forgeo start   # run forever: every interval_minutes, implement the oldest OPEN task
+```
+
+`forgeo init` writes `forgeo.yaml` and a `.forgeo/` folder for the backlog
+and logs, gitignored for you. Fill the backlog with plain JSON tasks (see
+[Backlog format](docs/backlog.md)) — or add them from the web console while
+it runs — and Forgeo does the rest. The daemon binds no ports; open the
+dashboard with `forgeo web` (default <http://0.0.0.0:8790>):
+
+![Forgeo web console](docs/img/console.png)
+
+One-off commands: `forgeo once` (single cycle), `forgeo status` (summary),
+`forgeo stop`, `forgeo restart` — every command is in the
+[CLI reference](docs/cli-reference.md).
+
+You can run several factories at once, one per repository — each config is
+fully independent (own backlog, logs, locks). Register each `forgeo.yaml`
+in the instance registry with `forgeo instance add NAME --config PATH`,
+manage any of them by name with `forgeo start/status/stop --name NAME`,
+list them all with `forgeo list`, and get one aggregate overview with the
+central dashboard, `forgeo web`.
+
+## Documentation
+
+| Topic | Where |
+| --- | --- |
+| Install, init, first cycle | [Getting started](docs/getting-started.md) |
+| Every `forgeo.yaml` key | [Configuration](docs/configuration.md) |
+| Task schema and statuses | [Backlog format](docs/backlog.md) |
+| How the agent is invoked (env, exit codes, timeouts) | [Agent contract](docs/agent-contract.md) |
+| All CLI commands | [CLI reference](docs/cli-reference.md) |
+| Web dashboard & HTTP API | [Web console & HTTP API](docs/web-console-api.md) |
+
+Everything is stored in plain files: the backlog, `forgeo.log`, and
+`BLOCKER.md` whenever a decision is pending.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup, quality
+gates (`pytest`, `ruff check`, `mypy src/forgeo`), and the pull-request
+process.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

forgeo_cli-0.3.0/README.md

@@ -0,0 +1,92 @@
+<div align="center">
+  <img src="docs/img/logo.png" alt="Forgeo logo" width="128">
+</div>
+
+<div align="center">
+  <img src="docs/img/title.svg" alt="Forgeo" width="128">
+</div>
+
+
+[![CI](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml/badge.svg)](https://github.com/lucaGazzola/forgeo/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Forgeo is an autonomous software forgeo for people with ideas, not teams.**
+You have a product idea — an app, a website, an internal automation — but no
+developers on staff. With Forgeo you don't need any: you write down what needs
+to be built as a simple list of tasks, and an AI coding agent works through the
+list on its own, writing the code and committing it to your repository. No
+branches, no pull requests, no developer to hire.
+
+All you need is basic comfort with a terminal, a git repository, and any coding
+agent CLI — Claude Code, aider, opencode, or your own script. Forgeo works with
+all of them.
+
+Forgeo decides what to do next on its own: while tasks are left it implements
+the oldest one and commits the result, and when the backlog is empty it reviews
+the codebase and cleans it up. It only interrupts you when a decision is
+genuinely yours to make — everything else happens autonomously.
+
+## Quickstart
+
+Requires a git repository (no Python needed — the one-liner downloads a
+prebuilt binary for your OS, or `pipx install forgeo-cli` works too). The full
+walkthrough is in [Getting started](docs/getting-started.md).
+
+```bash
+# 1. Install
+curl -fsSL https://forgeo.org/install.sh | bash
+
+# 2. Create your Forgeo (guided wizard, run from your project root)
+forgeo init
+
+# 3. Start Forgeo
+forgeo start   # run forever: every interval_minutes, implement the oldest OPEN task
+```
+
+`forgeo init` writes `forgeo.yaml` and a `.forgeo/` folder for the backlog
+and logs, gitignored for you. Fill the backlog with plain JSON tasks (see
+[Backlog format](docs/backlog.md)) — or add them from the web console while
+it runs — and Forgeo does the rest. The daemon binds no ports; open the
+dashboard with `forgeo web` (default <http://0.0.0.0:8790>):
+
+![Forgeo web console](docs/img/console.png)
+
+One-off commands: `forgeo once` (single cycle), `forgeo status` (summary),
+`forgeo stop`, `forgeo restart` — every command is in the
+[CLI reference](docs/cli-reference.md).
+
+You can run several factories at once, one per repository — each config is
+fully independent (own backlog, logs, locks). Register each `forgeo.yaml`
+in the instance registry with `forgeo instance add NAME --config PATH`,
+manage any of them by name with `forgeo start/status/stop --name NAME`,
+list them all with `forgeo list`, and get one aggregate overview with the
+central dashboard, `forgeo web`.
+
+## Documentation
+
+| Topic | Where |
+| --- | --- |
+| Install, init, first cycle | [Getting started](docs/getting-started.md) |
+| Every `forgeo.yaml` key | [Configuration](docs/configuration.md) |
+| Task schema and statuses | [Backlog format](docs/backlog.md) |
+| How the agent is invoked (env, exit codes, timeouts) | [Agent contract](docs/agent-contract.md) |
+| All CLI commands | [CLI reference](docs/cli-reference.md) |
+| Web dashboard & HTTP API | [Web console & HTTP API](docs/web-console-api.md) |
+
+Everything is stored in plain files: the backlog, `forgeo.log`, and
+`BLOCKER.md` whenever a decision is pending.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup, quality
+gates (`pytest`, `ruff check`, `mypy src/forgeo`), and the pull-request
+process.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

forgeo_cli-0.3.0/config/nginx-forgeo.conf

@@ -0,0 +1,40 @@
+# Serves the Forgeo website (/var/www/forgeo) for the public domain
+# forgeo.org: the landing page at the root, the MkDocs documentation
+# under /docs/. TLS is terminated by Nginx Proxy Manager (running on the
+# owner's LAN) which fronts this server; this nginx serves plain HTTP
+# on port 8080 so NPM can proxy to it as the backend.
+server {
+    listen 8080;
+    listen [::]:8080;
+
+    server_name _;
+
+    root /var/www/forgeo;
+    index index.html;
+
+    error_page 404 /404.html;
+
+    location / {
+        try_files $uri $uri/ /404.html;
+    }
+
+    # install.sh is served as plain text; it is a .sh file with no
+    # default nginx mime type, so it would otherwise go out as
+    # application/octet-stream.
+    location = /install.sh {
+        default_type text/plain;
+    }
+
+    # Hashed assets of the landing page and the MkDocs theme are
+    # immutable; static images (console.png, logo) are long-lived too.
+    location ~ ^/(assets|docs/assets)/ {
+        try_files $uri =404;
+        expires 7d;
+        add_header Cache-Control "public";
+    }
+
+    location /img/ {
+        expires 7d;
+        add_header Cache-Control "public";
+    }
+}