portlight 1.0.0__tar.gz

portlight-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - '.github/workflows/ci.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - '.github/workflows/ci.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]" ruff
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Test
+        run: pytest tests/ -x -q

portlight-1.0.0/.github/workflows/pages.yml

@@ -0,0 +1,50 @@
+name: Deploy Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'site/**'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install site dependencies
+        working-directory: site
+        run: npm ci
+
+      - name: Build site
+        working-directory: site
+        run: npm run build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

portlight-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

portlight-1.0.0/.github/workflows/release-binaries.yml

@@ -0,0 +1,80 @@
+name: Release Binaries
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+env:
+  TOOL_NAME: portlight
+  ENTRYPOINT: src/portlight/__main__.py
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: linux-x64
+            ext: ""
+          - os: macos-latest
+            target: darwin-arm64
+            ext: ""
+          - os: windows-latest
+            target: win-x64
+            ext: ".exe"
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v3
+
+      - run: uv python install 3.12
+
+      - run: uv venv
+
+      - name: Install dependencies + PyInstaller
+        run: uv pip install . "pyinstaller>=6.9.0"
+
+      - name: Build binary
+        shell: bash
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          uv run pyinstaller --onefile --name "${{ env.TOOL_NAME }}" --console \
+            --collect-submodules rich \
+            "${{ env.ENTRYPOINT }}"
+          OUTNAME="${{ env.TOOL_NAME }}-${VERSION}-${{ matrix.target }}${{ matrix.ext }}"
+          mv "dist/${{ env.TOOL_NAME }}${{ matrix.ext }}" "dist/${OUTNAME}"
+          echo "ASSET_NAME=${OUTNAME}" >> "$GITHUB_ENV"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: binary-${{ matrix.target }}
+          path: dist/${{ env.ASSET_NAME }}
+
+  release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          merge-multiple: true
+
+      - name: Generate checksums
+        shell: bash
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          cd artifacts
+          sha256sum * > "checksums-${VERSION}.txt"
+          cat "checksums-${VERSION}.txt"
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: artifacts/*

portlight-1.0.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.venv/
+venv/
+*.swp
+*.swo
+.DS_Store
+saves/
+site/.astro/
+site/dist/
+site/node_modules/
+.polyglot-cache.json

portlight-1.0.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0-alpha] - 2026-03-20
+
+### Added
+
+- **Economy** — scarcity-driven pricing across 10 ports, 8 goods, 17 routes with flood penalty and market shocks
+- **Voyages** — multi-day travel with storms, pirates, inspections, provisions, hull, and crew
+- **Captain identity** — merchant, smuggler, navigator with 8-20% pricing gaps and distinct access profiles
+- **Contracts** — 6 families with trust/standing gates, provenance-validated delivery, deadline tracking
+- **Reputation** — regional standing, customs heat, commercial trust, multi-axis access model
+- **Infrastructure** — warehouses (3 tiers), broker offices (2 tiers × 3 regions), 5 licenses with real upkeep
+- **Insurance** — hull, cargo, contract guarantee policies with heat surcharges and claim resolution
+- **Credit** — 3 tiers with interest accrual, payment deadlines, default consequences
+- **Campaign** — 27 milestones, 7 career profile tags, 4 victory paths with diagnostics
+- **Save/load** — full compound state round-trip (economy + contracts + infrastructure + insurance + credit + campaign)
+- **CLI** — 30 commands via Typer with Rich rendering, welcome screen, contextual hints, grouped guide
+- **Onboarding** — welcome view, hint system, flood explanation, contract deadline context, daily upkeep display
+- **Balance harness** — 7 policy bots, 7 scenario packs, structured JSON/markdown reporting
+- **Stress testing** — 14 cross-system invariants, 9 compound stress scenarios, trace recording
+- **Documentation** — README, START_HERE, FIRST_VOYAGE, COMMANDS, CAREER_PATHS, EXAMPLE_RUNS, ALPHA_STATUS, KNOWN_ISSUES, RELEASE_NOTES
+- 609 tests across 24 files

portlight-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+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.

portlight-1.0.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: portlight
+Version: 1.0.0
+Summary: Trade-first maritime strategy CLI — route arbitrage, contracts, infrastructure, finance, and commercial reputation across a living regional economy
+Author-email: mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,game,maritime,strategy,trading
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment :: Simulation
+Requires-Python: >=3.11
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/portlight/readme.png" width="800" alt="Portlight">
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/portlight/actions"><img src="https://github.com/mcp-tool-shop-org/portlight/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/mcp-tool-shop-org/portlight/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
+  <a href="https://mcp-tool-shop-org.github.io/portlight/"><img src="https://img.shields.io/badge/docs-landing_page-blue" alt="Landing Page"></a>
+</p>
+
+A trade-first maritime strategy CLI where you build a merchant career through route arbitrage, contracts, infrastructure, finance, and commercial reputation across a living regional economy.
+
+## Why Portlight
+
+Most trading games flatten trade into a number that goes up. Portlight treats trade as a commercial discipline:
+
+- **Prices react to your trades.** Dump grain at a port and the price crashes. Every sale shifts the local market.
+- **Ports have real economic identities.** Porto Novo produces grain cheaply. Al-Manar consumes silk hungrily. These aren't random — they're structural.
+- **Voyages carry risk.** Storms, pirates, inspections. Your provisions, hull, and crew matter.
+- **Contracts require proof.** Deliver the right goods to the right port with tracked provenance. No faking it.
+- **Infrastructure changes how you trade.** Warehouses let you stage cargo. Brokers improve contract quality. Licenses unlock premium access.
+- **Finance is leverage with teeth.** Credit lets you move faster. Default, and doors close.
+- **The game reads what you built.** Your trade history, infrastructure, reputation, and routes form a career profile. The game tells you what kind of trade house you actually are.
+
+## The Core Loop
+
+1. Inspect the market — find what's cheap here and expensive elsewhere
+2. Buy cargo — load your hold
+3. Sail — cross routes under weather, crew, and provision pressure
+4. Sell — earn margin, shift the local market
+5. Reinvest — upgrade your ship, lease a warehouse, open a broker office
+6. Build access — earn trust, reduce heat, unlock contracts and licenses
+7. Pursue a commercial destiny — four distinct victory paths based on what you actually built
+
+## Quick Start
+
+```bash
+# Install
+pip install -e ".[dev]"
+
+# Start a new game
+portlight new "Captain Hawk" --type merchant
+
+# Look at what's for sale
+portlight market
+
+# Buy cheap goods
+portlight buy grain 10
+
+# Check available routes
+portlight routes
+
+# Sail to where grain sells high
+portlight sail al_manar
+
+# Advance through the voyage
+portlight advance
+
+# Sell at destination
+portlight sell grain 10
+
+# See your trade history
+portlight ledger
+
+# Check your career progress
+portlight milestones
+```
+
+See [docs/START_HERE.md](docs/START_HERE.md) for a guided first session and [docs/FIRST_VOYAGE.md](docs/FIRST_VOYAGE.md) for a detailed early-game walkthrough.
+
+## Captain Types
+
+| Captain | Identity | Edge | Trade-off |
+|---------|----------|------|-----------|
+| **Merchant** | Licensed trader, Mediterranean base | Better prices, lower inspection rates, trust grows faster | No black market access |
+| **Smuggler** | Discreet operator, West Africa base | Black market access, luxury margins, contraband trade | Higher heat, more inspections |
+| **Navigator** | Deep-water explorer, Mediterranean base | Faster ships, longer range, East Indies access early | Weaker initial commercial standing |
+
+## Systems
+
+**Economy** — Scarcity-driven pricing across 10 ports, 8 goods, 17 routes. Flood penalties punish dumping. Market shocks create regional opportunities.
+
+**Voyages** — Multi-day travel with weather events, pirate encounters, inspections. Provisions, hull, and crew are real resources.
+
+**Captains** — Three distinct archetypes with 8-20% pricing gaps, unique starting positions, and different access profiles.
+
+**Contracts** — Six contract families gated by trust and standing. Provenance-validated delivery. Real deadlines with real consequences.
+
+**Reputation** — Regional standing, port-specific reputation, customs heat, and commercial trust. A multi-axis access model that opens and closes doors.
+
+**Infrastructure** — Warehouses (3 tiers), broker offices (2 tiers across 3 regions), and 5 purchasable licenses. Each changes trade timing, scale, or access.
+
+**Insurance** — Hull, cargo, and contract guarantee policies. Heat surcharges. Claim resolution with denial conditions.
+
+**Credit** — Three tiers of credit with interest accrual, payment deadlines, and default consequences. Leverage with real risk.
+
+**Career** — 27 milestones across 6 families. Career profile interpretation (primary/secondary/emerging tags). Four victory paths: Lawful Trade House, Shadow Network, Oceanic Reach, and Commercial Empire.
+
+## Victory Paths
+
+- **Lawful Trade House** — Disciplined legitimacy. High trust, premium contracts, clean reputation, infrastructure breadth.
+- **Shadow Network** — Profitable discreet trade. Luxury margins under scrutiny, heat management, resilient operations.
+- **Oceanic Reach** — Long-haul commercial power. East Indies access, distant infrastructure, premium route mastery.
+- **Commercial Empire** — Integrated multi-region operation. Infrastructure in every region, diversified revenue, financial leverage.
+
+See [docs/CAREER_PATHS.md](docs/CAREER_PATHS.md) for detailed player-facing descriptions.
+
+## Command Reference
+
+Run `portlight guide` in-game for a grouped command reference, or see [docs/COMMANDS.md](docs/COMMANDS.md).
+
+| Group | Commands |
+|-------|----------|
+| Trading | `market`, `buy`, `sell`, `cargo` |
+| Navigation | `routes`, `sail`, `advance`, `port`, `provision`, `repair`, `hire` |
+| Contracts | `contracts`, `accept`, `obligations`, `abandon` |
+| Infrastructure | `warehouse`, `office`, `license` |
+| Finance | `insure`, `credit` |
+| Career | `captain`, `reputation`, `milestones`, `status`, `ledger`, `shipyard` |
+| System | `save`, `load`, `guide` |
+
+## Alpha Status
+
+Portlight is in alpha. The core systems are complete and stress-tested, but balance is actively being tuned.
+
+**What's solid:**
+- All systems functional end-to-end
+- 609 tests across 24 files
+- 14 cross-system invariants enforced under 9 compound stress scenarios
+- Balance harness with 7 policy bots across 7 scenario packs
+
+**What's being tuned:**
+- Smuggler scaling (currently under-performing on ship progression)
+- Mediterranean route concentration (Porto Novo / Silva Bay dominates traffic)
+- Contract completion rates (delivery logic gaps in automated runs)
+- Insurance adoption (currently near zero in simulated play)
+
+See [docs/ALPHA_STATUS.md](docs/ALPHA_STATUS.md) for details and [docs/KNOWN_ISSUES.md](docs/KNOWN_ISSUES.md) for specific items.
+
+## Security and Data
+
+Portlight is a **local-only CLI game**. It makes zero network connections during gameplay. Data touched: local save files (`saves/`) and report artifacts (`artifacts/`), all JSON on the local filesystem. No secrets, credentials, telemetry, or remote services. No elevated permissions required. See [SECURITY.md](SECURITY.md) for the full policy.
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run balance simulation
+python tools/run_balance.py
+
+# Run stress tests
+python tools/run_stress.py
+
+# Lint
+ruff check src/ tests/
+```
+
+## License
+
+MIT
+
+---
+
+Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>

portlight-1.0.0/README.es.md

@@ -0,0 +1,173 @@
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.md">English</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/portlight/readme.png" width="400" alt="Portlight">
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/portlight/actions"><img src="https://github.com/mcp-tool-shop-org/portlight/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/mcp-tool-shop-org/portlight/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
+  <a href="https://mcp-tool-shop-org.github.io/portlight/"><img src="https://img.shields.io/badge/docs-landing_page-blue" alt="Landing Page"></a>
+</p>
+
+Una estrategia marítima centrada en el comercio, donde construyes una carrera como comerciante a través de la optimización de rutas, contratos, infraestructura, finanzas y reputación comercial en una economía regional dinámica.
+
+## ¿Por qué Portlight?
+
+La mayoría de los juegos de comercio simplifican el comercio a un número que simplemente aumenta. Portlight trata el comercio como una disciplina comercial:
+
+- **Los precios reaccionan a tus transacciones.** Si vendes grandes cantidades de grano en un puerto, el precio se desploma. Cada venta altera el mercado local.
+- **Los puertos tienen identidades económicas reales.** Porto Novo produce grano a bajo costo. Al-Manar consume seda con avidez. Estas características no son aleatorias, sino estructurales.
+- **Los viajes implican riesgos.** Tormentas, piratas, inspecciones. Tus provisiones, el casco y la tripulación son importantes.
+- **Los contratos requieren pruebas.** Debes entregar los productos correctos en el puerto correcto, con un registro de procedencia verificable. No se permiten falsificaciones.
+- **La infraestructura cambia la forma en que operas.** Los almacenes te permiten almacenar mercancías. Los intermediarios mejoran la calidad de los contratos. Las licencias desbloquean acceso premium.
+- **El crédito es una herramienta poderosa, pero con riesgos.** El crédito te permite actuar más rápido. Si incumples, perderás acceso a él.
+- **El juego evalúa lo que has construido.** Tu historial comercial, infraestructura, reputación y rutas forman un perfil de carrera. El juego te indica qué tipo de empresa comercial eres realmente.
+
+## El Ciclo Principal
+
+1. Analiza el mercado: encuentra qué productos son baratos aquí y caros en otro lugar.
+2. Compra mercancías: carga tu bodega.
+3. Navega: atraviesa rutas bajo la presión del clima, la tripulación y las provisiones.
+4. Vende: obtén ganancias, altera el mercado local.
+5. Reinvierta: mejora tu barco, alquila un almacén, abre una oficina de intermediarios.
+6. Construye acceso: gana confianza, reduce la atención negativa, desbloquea contratos y licencias.
+7. Persigue un destino comercial: cuatro caminos distintos hacia la victoria, basados en lo que realmente has construido.
+
+## Guía de inicio rápido
+
+```bash
+# Install
+pip install -e ".[dev]"
+
+# Start a new game
+portlight new "Captain Hawk" --type merchant
+
+# Look at what's for sale
+portlight market
+
+# Buy cheap goods
+portlight buy grain 10
+
+# Check available routes
+portlight routes
+
+# Sail to where grain sells high
+portlight sail al_manar
+
+# Advance through the voyage
+portlight advance
+
+# Sell at destination
+portlight sell grain 10
+
+# See your trade history
+portlight ledger
+
+# Check your career progress
+portlight milestones
+```
+
+Consulta [docs/START_HERE.md](docs/START_HERE.md) para una primera sesión guiada y [docs/FIRST_VOYAGE.md](docs/FIRST_VOYAGE.md) para una descripción detallada de las primeras etapas del juego.
+
+## Tipos de Capitanes
+
+| Capitán | Identidad | Ventaja | Compromiso |
+|---------|----------|------|-----------|
+| **Merchant** | Comerciante con licencia, base en el Mediterráneo | Mejores precios, tasas de inspección más bajas, la confianza crece más rápido. | Sin acceso al mercado negro. |
+| **Smuggler** | Operador discreto, base en África Occidental. | Acceso al mercado negro, márgenes de lujo, comercio de contrabando. | Mayor atención negativa, más inspecciones. |
+| **Navigator** | Explorador de aguas profundas, base en el Mediterráneo. | Barcos más rápidos, mayor alcance, acceso temprano a las Indias Orientales. | Posición comercial inicial más débil. |
+
+## Sistemas
+
+**Economía:** Precios determinados por la escasez en 10 puertos, 8 productos, 17 rutas. Las penalizaciones por sobreproducción castigan la venta masiva. Los shocks del mercado crean oportunidades regionales.
+
+**Viajes:** Viajes de varios días con eventos climáticos, encuentros con piratas e inspecciones. Las provisiones, el casco y la tripulación son recursos reales.
+
+**Capitanes:** Tres arquetipos distintos con diferencias de precios del 8 al 20%, posiciones de inicio únicas y diferentes perfiles de acceso.
+
+**Contratos:** Seis familias de contratos bloqueadas por la confianza y la reputación. Entrega con validación de procedencia. Plazos reales con consecuencias reales.
+
+**Reputación:** Posición regional, reputación específica de cada puerto, atención de las aduanas y confianza comercial. Un modelo de acceso de múltiples ejes que abre y cierra puertas.
+
+**Infraestructura:** Almacenes (3 niveles), oficinas de intermediarios (2 niveles en 3 regiones) y 5 licencias comprables. Cada una cambia el tiempo, la escala o el acceso al comercio.
+
+**Seguro:** Pólizas de seguro de casco, carga y garantía de contrato. Cargos por atención negativa. Resolución de reclamaciones con condiciones de denegación.
+
+**Crédito:** Tres niveles de crédito con acumulación de intereses, plazos de pago y consecuencias por incumplimiento. Una herramienta poderosa con riesgos reales.
+
+**Carrera** — 27 hitos en 6 categorías. Interpretación del perfil de carrera (etiquetas primarias/secundarias/emergentes). Cuatro caminos hacia la victoria: Casa Comercial Legítima, Red de la Sombra, Alcance Oceánico e Imperio Comercial.
+
+## Caminos hacia la Victoria
+
+- **Casa Comercial Legítima** — Legitimidad disciplinada. Alta confianza, contratos premium, reputación intachable, amplia infraestructura.
+- **Red de la Sombra** — Comercio discreto y rentable. Márgenes de lujo bajo escrutinio, gestión de riesgos, operaciones resilientes.
+- **Alcance Oceánico** — Poder comercial de largo alcance. Acceso a las Indias Orientales, infraestructura distante, dominio de rutas premium.
+- **Imperio Comercial** — Operación integrada en múltiples regiones. Infraestructura en cada región, diversificación de ingresos, apalancamiento financiero.
+
+Consulte [docs/CAREER_PATHS.md](docs/CAREER_PATHS.md) para obtener descripciones detalladas dirigidas al jugador.
+
+## Referencia de Comandos
+
+Ejecute `portlight guide` dentro del juego para obtener una referencia de comandos agrupada, o consulte [docs/COMMANDS.md](docs/COMMANDS.md).
+
+| Grupo | Comandos |
+|-------|----------|
+| Comercio | `market`, `buy`, `sell`, `cargo` |
+| Navegación | `routes`, `sail`, `advance`, `port`, `provision`, `repair`, `hire` |
+| Contratos | `contracts`, `accept`, `obligations`, `abandon` |
+| Infraestructura | `warehouse`, `office`, `license` |
+| Finanzas | `insure`, `credit` |
+| Carrera | `captain`, `reputation`, `milestones`, `status`, `ledger`, `shipyard` |
+| Sistema | `save`, `load`, `guide` |
+
+## Estado Alpha
+
+Portlight está en estado alpha. Los sistemas principales están completos y han sido sometidos a pruebas de estrés, pero el equilibrio se está ajustando activamente.
+
+**Lo que está funcionando correctamente:**
+- Todos los sistemas son funcionales de extremo a extremo.
+- 609 pruebas en 24 archivos.
+- 14 invariantes entre sistemas aplicadas bajo 9 escenarios de estrés compuestos.
+- Sistema de equilibrio con 7 bots de política en 7 paquetes de escenarios.
+
+**Lo que se está ajustando:**
+- Escalado de contrabandistas (actualmente con un rendimiento inferior en la progresión de la nave).
+- Concentración de rutas en el Mediterráneo (Porto Novo / Silva Bay dominan el tráfico).
+- Tasas de finalización de contratos (fallas en la lógica de entrega en ejecuciones automatizadas).
+- Adopción de seguros (actualmente cercana a cero en pruebas simuladas).
+
+Consulte [docs/ALPHA_STATUS.md](docs/ALPHA_STATUS.md) para obtener detalles y [docs/KNOWN_ISSUES.md](docs/KNOWN_ISSUES.md) para obtener información específica.
+
+## Seguridad y Datos
+
+Portlight es un juego de **línea de comandos que solo funciona localmente**. No realiza ninguna conexión de red durante el juego. Datos accedidos: archivos de guardado locales (`saves/`) y archivos de informe (`artifacts/`), todos en formato JSON en el sistema de archivos local. No hay secretos, credenciales, telemetría ni servicios remotos. No se requieren permisos elevados. Consulte [SECURITY.md](SECURITY.md) para obtener la política completa.
+
+## Desarrollo
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run balance simulation
+python tools/run_balance.py
+
+# Run stress tests
+python tools/run_stress.py
+
+# Lint
+ruff check src/ tests/
+```
+
+## Licencia
+
+MIT
+
+---
+
+Desarrollado por <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>