aa-planetary-operations 0.1.0__tar.gz

aa_planetary_operations-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,42 @@
+# Architecture
+
+## Modules
+
+| Module | Responsibility |
+|---|---|
+| `catalog.py`, `data/catalog.json` | Versioned, read-only commodity, recipe, planet, region and gate data |
+| `planner.py` | Recipe expansion, CP-SAT placement, material balance and regional hauling paths |
+| `characters.py` | AA ownership checks, scoped token selection, current PI skill/colony reads |
+| `esi.py` | Bounded HTTP reads and shared ESI cooldown |
+| `market.py` | Paginated Jita 4-4 buy order snapshots and depth-aware gross estimates |
+| `models.py`, `migrations/` | Owned skill snapshots and private saved plan inputs/results |
+| `forms.py`, `views.py`, `urls.py` | Validated user inputs, ownership-isolated access and exports |
+| `tasks.py` | Existing AA Celery worker integration, result persistence and failure reporting |
+| `auth_hooks.py` | AA sidebar permission and URL registration |
+| `tools/build_catalog.py` | Reproducible compiler for official CCP JSONL SDE archives |
+
+## Planning sequence
+
+1. Validate selection, tier, duration, extraction assumptions, output size and search limits.
+2. Aggregate ingredient demand in descending tier order. Round shared ingredients only after all parents contribute their demand. Stop recipe expansion at the selected import boundary.
+3. Split required batches into discrete processors using cycles available during the pull. Split P0 requirements into ECUs using assumed extraction capacity. Each task carries planet restrictions, CPU/power and exact input/output quantities.
+4. Give each character `1 + active Interplanetary Consolidation − occupied colonies` slots, or full capacity in replacement mode. Keep their Command Center Upgrades level and occupied planet IDs separate.
+5. Test single systems with OR-Tools CP-SAT. Every task is assigned once. Each used slot selects a system/planet type, respects the owning character's command-center budget plus launchpad/link reserve, and consumes one distinct available planet for that character. Different characters may each colonize the same planet.
+6. Skip resource-incompatible systems. Equivalent planet-type inventories share infeasibility proofs only when occupied planet IDs cannot distinguish them. A solver timeout is never an infeasibility proof.
+7. Only after all single-system candidates are excluded or proven infeasible, expand through regional stargate neighborhoods in increasing radius. Minimize systems first, colonies second within each candidate set. Report the first feasible nearby network without claiming a global minimum.
+8. Allocate concrete planet IDs, reserve local material consumption, then generate inter-colony movements. Material shortages abort the plan. Record remaining product/surplus, shortest regional gate paths and average-volume pad-service estimates.
+9. Fetch all pages of the finished product's regional buy orders; retain Jita 4-4 orders, respect remaining volume and minimum fills, and save timestamped gross estimates.
+
+## Ownership and failures
+
+Views require AA login and `planetary_operations.basic_access`. Every plan query is constrained to `owner=request.user`. Form choices are built from the user's AA ownership records; submitted IDs are validated against those choices. CSRF protects mutation endpoints; deletes, refreshes and price updates require POST.
+
+Tokens must match user, character, owner hash and both required scopes. Character ownership is rechecked after private ESI reads, and selected IDs are rechecked before a completed plan is saved. Active skill levels are used. Failed reads are never substituted with zero skills or an empty colony list.
+
+Queued plan creation commits before task submission. A conditional status transition prevents duplicate tasks from calculating the same plan. Task failures become readable saved-plan errors. Market failure leaves the production plan intact. Abandoned tasks can be released with the recovery command after a worker outage.
+
+Snapshots contain skills, occupied planet IDs and timestamps, never OAuth tokens. Export contains plan settings, character planning capacities and results only. Saved plans are historical snapshots and do not continuously reserve colonies or update themselves.
+
+## Deliberate V1 bounds
+
+Ten selected characters; at most 240 individual facilities; 1–336 hours per pull; 0–5 regional gate jumps from a search center; bounded solver time. The user supplies one common average extraction assumption. Exact pin coordinates, production simulation over time, financial profit, sovereignty/POCO permissions, and global multi-system optimality are outside this implementation's claims.

aa_planetary_operations-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AA Planetary Operations 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.

aa_planetary_operations-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md ARCHITECTURE.md VERIFICATION.md NOTICE.md LICENSE
+recursive-include planetary_operations/data *.json
+recursive-include planetary_operations/templates *.html
+recursive-include planetary_operations/static *.css *.js
+recursive-include tests *.py
+recursive-include tools *.py
+recursive-include docs *.md *.png

aa_planetary_operations-0.1.0/NOTICE.md

@@ -0,0 +1,7 @@
+# Game-data notice
+
+EVE Online, the EVE logo, and EVE game data are the intellectual property of CCP hf. This community application is not affiliated with or endorsed by CCP or the Alliance Auth project.
+
+The bundled catalog is derived from the official EVE Online Static Data Export. Access and use of EVE APIs and static data remain subject to CCP's applicable developer terms. No license to CCP's trademarks or game data is granted by this application's source-code license.
+
+The dependency packages retain their own licenses. Alliance Auth is GPL-licensed; review its distribution requirements when distributing combined deployments.

aa_planetary_operations-0.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: aa-planetary-operations
+Version: 0.1.0
+Summary: Multi-character planetary industry planning for Alliance Auth v5
+Author: jaybone26
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jaybone26/aa-planetary-operations
+Project-URL: Documentation, https://github.com/jaybone26/aa-planetary-operations#readme
+Project-URL: Repository, https://github.com/jaybone26/aa-planetary-operations
+Project-URL: Issues, https://github.com/jaybone26/aa-planetary-operations/issues
+Keywords: allianceauth,eve-online,planetary-industry
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE.md
+Requires-Dist: allianceauth<6,>=5.0
+Requires-Dist: requests<3,>=2.32
+Requires-Dist: ortools<10,>=9.10
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-django>=4.8; extra == "test"
+Requires-Dist: requests-mock>=1.12; extra == "test"
+Requires-Dist: fakeredis>=2; extra == "test"
+Requires-Dist: ruff; extra == "test"
+Requires-Dist: build; extra == "test"
+Dynamic: license-file
+
+![Version](https://img.shields.io/badge/version-0.1.0-blue)
+![Alliance Auth](https://img.shields.io/badge/Alliance_Auth-v5-blue)
+![Python](https://img.shields.io/badge/Python-3.11%2B-blue)
+![Django](https://img.shields.io/badge/Django-5.2-green)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/LICENSE)
+[![Verification](https://img.shields.io/badge/local_tests-36_passed-brightgreen)](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/VERIFICATION.md)
+![Status](https://img.shields.io/badge/status-staging-orange)
+
+# AA Planetary Operations for Alliance Auth
+
+Plan your planetary industry across your main and alts, build the production network, and see its Jita buy value per pull.
+
+---
+
+## Contents
+
+- [Features](#features)
+- [Upcoming](#upcoming)
+- [Highlights](#highlights)
+- [Installation](#installation)
+  - [Step 1 — Install the package](#step-1--install-the-package)
+  - [Step 2 — Configure Alliance Auth](#step-2--configure-alliance-auth)
+  - [Step 3 — Configure ESI access](#step-3--configure-esi-access)
+  - [Step 4 — Run migrations and collect static files](#step-4--run-migrations-and-collect-static-files)
+  - [Step 5 — Set up permissions](#step-5--set-up-permissions)
+  - [Step 6 — Authorize characters and build a plan](#step-6--authorize-characters-and-build-a-plan)
+- [Settings](#settings)
+- [Using the planner](#using-the-planner)
+- [Translations](#translations)
+- [Contributing](#contributing)
+- [License and credits](#license-and-credits)
+
+## Features
+
+- **Main and alt planning** — combine up to ten AA-authenticated characters in one operation.
+- **Automatic PI skill reads** — use active skill levels and existing colonies to determine available capacity.
+- **P0 through P4** — choose any of the 83 PI commodities as your finished product.
+- **Import tiers** — extract from P0 or start with supplied P1, P2, or P3 materials.
+- **Region selection** — use real planet types, resources, recipes, and stargate connections from CCP's static data.
+- **One system first** — try single-system layouts before expanding into nearby systems.
+- **Character assignments** — fit colonies and facilities within each character's skill limits.
+- **Build sheets** — see each planet, command-center level, extractor, processor, and required material.
+- **Logistics plans** — get import quantities, local routes, character handoffs, hauling volumes, and regional gate paths.
+- **Extraction schedules** — set the pull duration, output target, assumed extraction yield, and extractor head count.
+- **Jita buy valuation** — estimate gross ISK per pull, day, and week from Jita 4-4 buy orders and available order volume.
+- **Saved operations** — keep private plans, adjust a copy, refresh prices, or export the build sheet.
+
+## Upcoming
+
+Future possibilities beyond V1:
+
+- Discord alerts.
+- Alliance-wide collaborative production and suppliers.
+- Advanced POCO tools.
+- Historical production and market analytics.
+
+## Highlights
+
+### Characters and operation planner
+
+Select your authenticated characters and configure the production chain in one place.
+
+![AA Planetary Operations — characters and planner](https://raw.githubusercontent.com/jaybone26/aa-planetary-operations/HEAD/docs/images/planner.png)
+
+### Production overview
+
+Review estimated output, deployment size, and the Jita valuation status for a saved operation.
+
+![AA Planetary Operations — saved operation overview](https://raw.githubusercontent.com/jaybone26/aa-planetary-operations/HEAD/docs/images/operation.png)
+
+*Screenshots show a local demonstration using sample characters. Market pricing is unavailable in the pictured preview; the live public ESI check is recorded in [Verification](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/VERIFICATION.md).*
+
+## Installation
+
+> **Requirements:** Alliance Auth v5, Python 3.11+, and your existing Auth database, Redis/Valkey, and Celery worker.
+>
+> Version 0.1.0 is ready for staging evaluation. Install it directly into your Alliance Auth virtual environment. Complete a real SSO authorization and worker run on your server before rollout.
+
+### Step 1 — Install the package
+
+Activate the virtual environment used by your Alliance Auth installation, then install the supplied wheel:
+
+```shell
+python -m pip install /path/to/aa_planetary_operations-0.1.0-py3-none-any.whl
+```
+
+Alternatively, install from the source directory:
+
+```shell
+python -m pip install /path/to/aa-planetary-operations
+```
+
+PyPI publication is pending. Maintainers can follow the [Publishing guide](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/docs/PUBLISHING.md) to configure the first release.
+
+### Step 2 — Configure Alliance Auth
+
+Add the app in your Auth project's `settings/local.py`:
+
+```python
+INSTALLED_APPS += [
+    "planetary_operations",
+]
+```
+
+Set a User-Agent that identifies your deployment and administrator contact:
+
+```python
+PLANETARY_OPERATIONS_USER_AGENT = "AA-Planetary-Operations/0.1.0 (your administrator contact)"
+PLANETARY_OPERATIONS_SEARCH_SECONDS = 30
+```
+
+The package includes its PI and universe catalog. A separate SDE app or initial data download is not required.
+
+### Step 3 — Configure ESI access
+
+Enable the following scopes on the EVE developer application used by your Auth installation:
+
+| Scope | Purpose |
+| :--- | :--- |
+| `esi-skills.read_skills.v1` | Read each character's active PI skill levels. |
+| `esi-planets.manage_planets.v1` | Read existing colonies and occupied planet IDs. |
+
+Keep your existing AA SSO callback URL. Users grant these scopes through **Authorize a character’s PI access**. The plugin only reads ESI, including the scope named “manage”; it makes no in-game changes.
+
+### Step 4 — Run migrations and collect static files
+
+From your Auth project directory:
+
+```shell
+python manage.py migrate
+python manage.py collectstatic --noinput
+python manage.py check
+```
+
+Restart your existing Auth web processes and Celery workers through your normal service manager.
+
+Plan calculations use the task `planetary_operations.tasks.calculate_plan` on the existing AA worker. No additional Celery Beat schedule is required.
+
+### Step 5 — Set up permissions
+
+Grant this permission to the appropriate AA group or state:
+
+| Permission | Description | Access |
+| :--- | :--- | :--- |
+| `planetary_operations.basic_access` | Can use Planetary Operations | Opens the app and allows users to create and manage their own plans. |
+
+The sidebar entry appears for permitted users. Saved plans are private to their owner.
+
+### Step 6 — Authorize characters and build a plan
+
+1. Open **Planetary Operations** from the AA sidebar.
+2. Attach any missing alts to your AA account.
+3. Use **Authorize a character’s PI access** for each character.
+4. Select the characters, finished product, import tier, and region.
+5. Set the pull duration and output target. Enter an extraction estimate based on your in-game program.
+6. Select **Build & save plan**. The result page updates when the worker finishes.
+
+## Settings
+
+Optional settings in `settings/local.py`:
+
+| Setting | Description | Default |
+| :--- | :--- | :--- |
+| `PLANETARY_OPERATIONS_USER_AGENT` | Identifies your application to ESI. Set it to include your administrator contact. | `AA-Planetary-Operations/0.1.0` |
+| `PLANETARY_OPERATIONS_SEARCH_SECONDS` | Solver search budget in seconds, limited to 5–120. | `30` |
+
+## Using the planner
+
+Existing colonies reduce available slots by default. Enable **Plan a replacement for my existing colonies** if you intend to rebuild them in game. Saved plans are alternative layouts; they do not reserve colony slots against each other.
+
+**Read estimates as steady-state targets.** The planner checks factory cycles and fitting budgets against your requested output. Future extraction yield, resource hotspots, exact link placement, startup buffers, sovereignty, and POCO access need an in-game check. Nearby-system results report a feasible network without claiming a global regional optimum.
+
+**Jita estimates are gross value.** Imported materials, taxes, fees, and hauling costs are excluded. Unfilled buy-order volume is reported. Day/week figures extrapolate the current pull valuation; future liquidity can change.
+
+For the full assumptions, operating instructions, catalog updates, and troubleshooting, see the [Operating guide](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/docs/OPERATING_GUIDE.md).
+
+## Translations
+
+The V1 interface is currently in English. Translation support is not included in this release.
+
+## Contributing
+
+Development uses a standard Python virtual environment. See the [Development guide](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/docs/DEVELOPMENT.md) for setup and verification commands.
+
+- [Architecture](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/ARCHITECTURE.md) — modules, planning constraints, and ownership checks.
+- [Verification](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/VERIFICATION.md) — completed tests, AA version checks, and live-data results.
+- [Operating guide](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/docs/OPERATING_GUIDE.md) — behavior to preserve when changing the planner.
+
+Include relevant tests with changes to production calculations, character permissions, or market handling.
+
+## License and credits
+
+Source code is available under the [MIT License](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/LICENSE).
+
+Built for [Alliance Auth](https://allianceauth.readthedocs.io/) using [Django-ESI](https://django-esi.readthedocs.io/) token management, CCP's [Static Data Export](https://developers.eveonline.com/docs/services/static-data/), and the [EVE ESI API](https://esi.evetech.net/ui/).
+
+EVE Online and its game data belong to CCP. See [NOTICE.md](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/NOTICE.md).

aa_planetary_operations-0.1.0/README.md

@@ -0,0 +1,197 @@
+![Version](https://img.shields.io/badge/version-0.1.0-blue)
+![Alliance Auth](https://img.shields.io/badge/Alliance_Auth-v5-blue)
+![Python](https://img.shields.io/badge/Python-3.11%2B-blue)
+![Django](https://img.shields.io/badge/Django-5.2-green)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/LICENSE)
+[![Verification](https://img.shields.io/badge/local_tests-36_passed-brightgreen)](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/VERIFICATION.md)
+![Status](https://img.shields.io/badge/status-staging-orange)
+
+# AA Planetary Operations for Alliance Auth
+
+Plan your planetary industry across your main and alts, build the production network, and see its Jita buy value per pull.
+
+---
+
+## Contents
+
+- [Features](#features)
+- [Upcoming](#upcoming)
+- [Highlights](#highlights)
+- [Installation](#installation)
+  - [Step 1 — Install the package](#step-1--install-the-package)
+  - [Step 2 — Configure Alliance Auth](#step-2--configure-alliance-auth)
+  - [Step 3 — Configure ESI access](#step-3--configure-esi-access)
+  - [Step 4 — Run migrations and collect static files](#step-4--run-migrations-and-collect-static-files)
+  - [Step 5 — Set up permissions](#step-5--set-up-permissions)
+  - [Step 6 — Authorize characters and build a plan](#step-6--authorize-characters-and-build-a-plan)
+- [Settings](#settings)
+- [Using the planner](#using-the-planner)
+- [Translations](#translations)
+- [Contributing](#contributing)
+- [License and credits](#license-and-credits)
+
+## Features
+
+- **Main and alt planning** — combine up to ten AA-authenticated characters in one operation.
+- **Automatic PI skill reads** — use active skill levels and existing colonies to determine available capacity.
+- **P0 through P4** — choose any of the 83 PI commodities as your finished product.
+- **Import tiers** — extract from P0 or start with supplied P1, P2, or P3 materials.
+- **Region selection** — use real planet types, resources, recipes, and stargate connections from CCP's static data.
+- **One system first** — try single-system layouts before expanding into nearby systems.
+- **Character assignments** — fit colonies and facilities within each character's skill limits.
+- **Build sheets** — see each planet, command-center level, extractor, processor, and required material.
+- **Logistics plans** — get import quantities, local routes, character handoffs, hauling volumes, and regional gate paths.
+- **Extraction schedules** — set the pull duration, output target, assumed extraction yield, and extractor head count.
+- **Jita buy valuation** — estimate gross ISK per pull, day, and week from Jita 4-4 buy orders and available order volume.
+- **Saved operations** — keep private plans, adjust a copy, refresh prices, or export the build sheet.
+
+## Upcoming
+
+Future possibilities beyond V1:
+
+- Discord alerts.
+- Alliance-wide collaborative production and suppliers.
+- Advanced POCO tools.
+- Historical production and market analytics.
+
+## Highlights
+
+### Characters and operation planner
+
+Select your authenticated characters and configure the production chain in one place.
+
+![AA Planetary Operations — characters and planner](https://raw.githubusercontent.com/jaybone26/aa-planetary-operations/HEAD/docs/images/planner.png)
+
+### Production overview
+
+Review estimated output, deployment size, and the Jita valuation status for a saved operation.
+
+![AA Planetary Operations — saved operation overview](https://raw.githubusercontent.com/jaybone26/aa-planetary-operations/HEAD/docs/images/operation.png)
+
+*Screenshots show a local demonstration using sample characters. Market pricing is unavailable in the pictured preview; the live public ESI check is recorded in [Verification](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/VERIFICATION.md).*
+
+## Installation
+
+> **Requirements:** Alliance Auth v5, Python 3.11+, and your existing Auth database, Redis/Valkey, and Celery worker.
+>
+> Version 0.1.0 is ready for staging evaluation. Install it directly into your Alliance Auth virtual environment. Complete a real SSO authorization and worker run on your server before rollout.
+
+### Step 1 — Install the package
+
+Activate the virtual environment used by your Alliance Auth installation, then install the supplied wheel:
+
+```shell
+python -m pip install /path/to/aa_planetary_operations-0.1.0-py3-none-any.whl
+```
+
+Alternatively, install from the source directory:
+
+```shell
+python -m pip install /path/to/aa-planetary-operations
+```
+
+PyPI publication is pending. Maintainers can follow the [Publishing guide](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/docs/PUBLISHING.md) to configure the first release.
+
+### Step 2 — Configure Alliance Auth
+
+Add the app in your Auth project's `settings/local.py`:
+
+```python
+INSTALLED_APPS += [
+    "planetary_operations",
+]
+```
+
+Set a User-Agent that identifies your deployment and administrator contact:
+
+```python
+PLANETARY_OPERATIONS_USER_AGENT = "AA-Planetary-Operations/0.1.0 (your administrator contact)"
+PLANETARY_OPERATIONS_SEARCH_SECONDS = 30
+```
+
+The package includes its PI and universe catalog. A separate SDE app or initial data download is not required.
+
+### Step 3 — Configure ESI access
+
+Enable the following scopes on the EVE developer application used by your Auth installation:
+
+| Scope | Purpose |
+| :--- | :--- |
+| `esi-skills.read_skills.v1` | Read each character's active PI skill levels. |
+| `esi-planets.manage_planets.v1` | Read existing colonies and occupied planet IDs. |
+
+Keep your existing AA SSO callback URL. Users grant these scopes through **Authorize a character’s PI access**. The plugin only reads ESI, including the scope named “manage”; it makes no in-game changes.
+
+### Step 4 — Run migrations and collect static files
+
+From your Auth project directory:
+
+```shell
+python manage.py migrate
+python manage.py collectstatic --noinput
+python manage.py check
+```
+
+Restart your existing Auth web processes and Celery workers through your normal service manager.
+
+Plan calculations use the task `planetary_operations.tasks.calculate_plan` on the existing AA worker. No additional Celery Beat schedule is required.
+
+### Step 5 — Set up permissions
+
+Grant this permission to the appropriate AA group or state:
+
+| Permission | Description | Access |
+| :--- | :--- | :--- |
+| `planetary_operations.basic_access` | Can use Planetary Operations | Opens the app and allows users to create and manage their own plans. |
+
+The sidebar entry appears for permitted users. Saved plans are private to their owner.
+
+### Step 6 — Authorize characters and build a plan
+
+1. Open **Planetary Operations** from the AA sidebar.
+2. Attach any missing alts to your AA account.
+3. Use **Authorize a character’s PI access** for each character.
+4. Select the characters, finished product, import tier, and region.
+5. Set the pull duration and output target. Enter an extraction estimate based on your in-game program.
+6. Select **Build & save plan**. The result page updates when the worker finishes.
+
+## Settings
+
+Optional settings in `settings/local.py`:
+
+| Setting | Description | Default |
+| :--- | :--- | :--- |
+| `PLANETARY_OPERATIONS_USER_AGENT` | Identifies your application to ESI. Set it to include your administrator contact. | `AA-Planetary-Operations/0.1.0` |
+| `PLANETARY_OPERATIONS_SEARCH_SECONDS` | Solver search budget in seconds, limited to 5–120. | `30` |
+
+## Using the planner
+
+Existing colonies reduce available slots by default. Enable **Plan a replacement for my existing colonies** if you intend to rebuild them in game. Saved plans are alternative layouts; they do not reserve colony slots against each other.
+
+**Read estimates as steady-state targets.** The planner checks factory cycles and fitting budgets against your requested output. Future extraction yield, resource hotspots, exact link placement, startup buffers, sovereignty, and POCO access need an in-game check. Nearby-system results report a feasible network without claiming a global regional optimum.
+
+**Jita estimates are gross value.** Imported materials, taxes, fees, and hauling costs are excluded. Unfilled buy-order volume is reported. Day/week figures extrapolate the current pull valuation; future liquidity can change.
+
+For the full assumptions, operating instructions, catalog updates, and troubleshooting, see the [Operating guide](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/docs/OPERATING_GUIDE.md).
+
+## Translations
+
+The V1 interface is currently in English. Translation support is not included in this release.
+
+## Contributing
+
+Development uses a standard Python virtual environment. See the [Development guide](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/docs/DEVELOPMENT.md) for setup and verification commands.
+
+- [Architecture](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/ARCHITECTURE.md) — modules, planning constraints, and ownership checks.
+- [Verification](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/VERIFICATION.md) — completed tests, AA version checks, and live-data results.
+- [Operating guide](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/docs/OPERATING_GUIDE.md) — behavior to preserve when changing the planner.
+
+Include relevant tests with changes to production calculations, character permissions, or market handling.
+
+## License and credits
+
+Source code is available under the [MIT License](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/LICENSE).
+
+Built for [Alliance Auth](https://allianceauth.readthedocs.io/) using [Django-ESI](https://django-esi.readthedocs.io/) token management, CCP's [Static Data Export](https://developers.eveonline.com/docs/services/static-data/), and the [EVE ESI API](https://esi.evetech.net/ui/).
+
+EVE Online and its game data belong to CCP. See [NOTICE.md](https://github.com/jaybone26/aa-planetary-operations/blob/HEAD/NOTICE.md).

aa_planetary_operations-0.1.0/VERIFICATION.md

@@ -0,0 +1,50 @@
+# Verification — V1 0.1.0
+
+Verified locally on September 29, 2026.
+
+## Environment
+
+- Python 3.12.14, Windows host, isolated virtual environment.
+- Alliance Auth **5.4.0**, Django **5.2.17**, Django-ESI **9.10.0**, OR-Tools **9.15.6755**.
+- The same test suite also passes with **Alliance Auth 5.0.0**, using the same other installed dependencies. This is a baseline compatibility check, not a matrix of every historic dependency combination.
+- Real AA app registrations, ownership models, URL hooks, templates, and database migrations; test-only SQLite, in-memory Redis substitute and mocked ESI transport.
+
+## Completed checks
+
+- **36 automated tests passed** on both AA 5.4.0 and AA 5.0.0.
+- Catalog coverage: all 83 commodities, every supported starting tier, acyclic tier dependencies and nonempty planet compatibility.
+- Planning: shared recipe requirements, whole-batch rounding, import boundaries including lower-tier P4 ingredients, skill budgets, occupied colonies, multi-character use, P4 planet restrictions, per-day/week normalization, real gate expansion and disconnected-system rejection.
+- Security/integration: AA template rendering, permissions, character ownership, token ownership/hash/scopes, active rather than trained skill levels, private saved-plan views/exports, CSRF and POST-only deletion, transaction-aware queue submission, worker failure handling, duplicate delivery handling, saved results with unavailable market data.
+- Market: station/order-side filtering, all-page retrieval, cache reuse, order depth, minimum quantities, missing prices, partial-page failure, and rate-limit cooldown.
+- Django model/template/URL/static-file checks passed without issues.
+- Migration drift check passed; fresh AA test databases apply the real app migrations successfully.
+- Python lint and formatting checks passed.
+- Wheel and source distribution built successfully. The wheel was installed into a separate directory, its catalog/migrations/templates/static assets were checked, and all 36 tests passed against the installed package.
+- Actual AA-rendered planner and production-result pages inspected in the in-app browser.
+
+## Live public-data smoke test
+
+The bundled catalog was compiled from official CCP SDE build **3552227**.
+
+Using the public ESI market endpoint on **2026-09-29 at 22:38 UTC**, the application retrieved Jita 4-4 buy orders for Broadcast Nodes and valued six units at **11,748,000 ISK gross**, with six filled and zero unfilled. This is a historical verification snapshot, not a current price recommendation.
+
+With three synthetic characters at IC V / CCU V and the documented default extraction assumptions, the engine found single-system layouts in Vale of the Silent for:
+
+| Target | Import tier | Target per 24-hour pull | Colonies |
+|---|---|---:|---:|
+| Broadcast Node | P0 extraction | 6 | 7 |
+| Wetware Mainframe | P0 extraction | 6 | 9 |
+| Robotics | P0 extraction | 24 | 2 |
+| Broadcast Node | Import P3/lower | 24 | 1 |
+| Aqueous Liquids | P0 extraction | 144,000 | 1 |
+
+These examples demonstrate solver behavior on the real catalog, not measured in-game extraction or a recommendation to deploy in those systems.
+
+## Still requires the target AA server
+
+- Real character SSO authorization with the deployment's EVE developer application.
+- End-to-end execution on its existing Linux Celery worker and Redis/Valkey broker.
+- Its production database and reverse-proxy configuration.
+- In-game resource yield, pin placement/link capacity, sovereignty and POCO access, startup buffers, and actual hauling cadence.
+
+No changes were made to a live AA installation or any EVE character. Use a staging installation first; the package is ready for that installation step.