portolan-cli 0.1.2__tar.gz → 0.1.3__tar.gz

{portolan_cli-0.1.2 → portolan_cli-0.1.3}/.github/workflows/nightly.yml

@@ -65,7 +65,7 @@ jobs:
         run: uv run mutmut html || true
 
       - name: Upload mutation report
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: mutation-report
           path: html/
@@ -113,7 +113,7 @@ jobs:
           fi
 
       - name: Upload benchmark results
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: benchmark-results
           path: benchmark-results.json

{portolan_cli-0.1.2 → portolan_cli-0.1.3}/.pre-commit-config.yaml

@@ -10,6 +10,7 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
+        args: ['--unsafe']  # Allow Python tags in mkdocs.yml
       - id: check-added-large-files
         args: ['--maxkb=500']
       - id: check-merge-conflict

{portolan_cli-0.1.2 → portolan_cli-0.1.3}/CHANGELOG.md

@@ -1,3 +1,9 @@
+## v0.1.3 (2026-02-05)
+
+### Fix
+
+- **docs**: use absolute GitHub URL for ADR link in roadmap
+
 ## v0.1.2 (2026-02-04)
 
 ### Fix

{portolan_cli-0.1.2 → portolan_cli-0.1.3}/CLAUDE.md

@@ -1,5 +1,22 @@
 # Portolan CLI - Development Guide
 
+## What is Portolan?
+
+Portolan is a CLI for publishing and managing **cloud-native geospatial data catalogs**. It orchestrates format conversion (GeoParquet, COG), versioning, and sync to object storage (S3, GCS, Azure)—no running servers, just static files.
+
+**Key concepts:**
+- **STAC** (SpatioTemporal Asset Catalog) — The catalog metadata format
+- **GeoParquet** — Cloud-optimized vector data (columnar, spatial indexing)
+- **COG** (Cloud-Optimized GeoTIFF) — Cloud-optimized raster data (HTTP range requests)
+- **versions.json** — Single source of truth for version history, sync state, and checksums
+
+Portolan doesn't do the heavy lifting—it orchestrates libraries like `geoparquet-io` and `rio-cogeo`.
+
+**Key dependencies (check these repos for API docs):**
+- [geoparquet-io](https://github.com/geoparquet/geoparquet-io) — Vector format conversion
+- [gpio-pmtiles](https://github.com/geoparquet-io/gpio-pmtiles) — PMTiles generation from GeoParquet
+- [rio-cogeo](https://github.com/cogeotiff/rio-cogeo) — Raster conversion to COG
+
 ## Guiding Principle
 
 AI agents will write most of the code. Human review does not scale to match AI output volume. Therefore: every quality gate must be automated, every convention must be enforceable, and tests must be verified to actually test something.
@@ -8,7 +25,9 @@ AI agents will write most of the code. Human review does not scale to match AI o
 
 | Resource | Location |
 |----------|----------|
+| **Roadmap** | `ROADMAP.md` |
 | Contributing guide | `docs/contributing.md` |
+| Architecture | `context/architecture.md` |
 | CI/CD documentation | `context/shared/documentation/ci.md` |
 | Distill MCP tools | `context/shared/documentation/distill-mcp.md` |
 | ADRs | `context/shared/adr/` |
@@ -16,6 +35,19 @@ AI agents will write most of the code. Human review does not scale to match AI o
 
 **Target Python version:** 3.10+ (matches geoparquet-io dependency)
 
+### ADR Index
+
+| ADR | Decision |
+|-----|----------|
+| [0001](context/shared/adr/0001-agentic-first-development.md) | Agentic-first: automate all quality gates, TDD mandatory |
+| [0002](context/shared/adr/0002-click-for-cli.md) | Click for CLI framework |
+| [0003](context/shared/adr/0003-plugin-architecture.md) | Plugin architecture for formats (GeoParquet/COG core, others optional) |
+| [0004](context/shared/adr/0004-iceberg-as-plugin.md) | Iceberg as plugin, STAC remains catalog layer |
+| [0005](context/shared/adr/0005-versions-json-source-of-truth.md) | versions.json as single source of truth |
+| [0006](context/shared/adr/0006-remote-ownership-model.md) | Portolan owns bucket contents (no external edits) |
+| [0007](context/shared/adr/0007-cli-wraps-api.md) | CLI wraps Python API (all logic in library layer) |
+| [0008](context/shared/adr/0008-pipx-for-installation.md) | pipx for global installation, uv for development |
+
 ## Common Commands
 
 ```bash
@@ -125,11 +157,7 @@ Store small, representative data files in `tests/fixtures/`. Fixtures should be:
 
 ### Pre-commit Hooks
 
-Pre-commit blocks on ALL checks. Install with `uv run pre-commit install`.
-
-Hooks run: trailing-whitespace, end-of-file-fixer, check-yaml, check-toml, check-merge-conflict, mixed-line-ending, check-added-large-files, ruff (fix + format), vulture, xenon, mypy, fast unit tests, commitizen (commit-msg).
-
-If a hook fails, fix the issue before committing. No `--no-verify`.
+Install: `uv run pre-commit install`. All hooks block—no `--no-verify`. See `.pre-commit-config.yaml` for full list.
 
 ## Code Quality
 
@@ -202,13 +230,6 @@ Releases are automated via commitizen on push to main. See `.github/workflows/re
 | API contracts | Docstrings | All public functions/classes |
 | Gotchas/quirks | CLAUDE.md or inline | Anything that surprised you |
 
-### Why This Matters
-
-- **AI agents start fresh each session** — They don't remember past conversations
-- **Context files are their memory** — ADRs, known-issues, and CLAUDE.md persist knowledge
-- **Documentation compounds** — Each documented decision helps all future sessions
-- **Undocumented knowledge is lost** — If it's not written down, it doesn't exist for agents
-
 ### ADR Guidelines
 
 Create an ADR (`context/shared/adr/NNNN-title.md`) when:
@@ -222,25 +243,10 @@ Use the template at `context/shared/adr/0000-template.md`.
 
 ### Two Documentation Audiences
 
-| Audience | Location | Optimized For |
-|----------|----------|---------------|
-| **Humans** | `docs/` (mkdocs) | Readability, navigation, tutorials, visual presentation |
-| **AI agents** | Docstrings, CLAUDE.md, ADRs, inline comments | Context windows, searchability, co-location with code |
-
-**Human docs (`docs/`):**
-- Rendered website via mkdocs
-- Prose-heavy with examples and screenshots
-- Organized by user journey (getting started → advanced topics)
-- Can be verbose — humans skim and navigate
-
-**AI docs (in-repo):**
-- Docstrings: Complete API contracts (args, returns, raises, examples)
-- CLAUDE.md: Development patterns, commands, gotchas
-- ADRs: Decision rationale with alternatives considered
-- Inline comments: Non-obvious code behavior
-- Dense and structured (tables, bullet lists) — agents parse linearly
-
-**Key difference:** Human docs explain *how to use* the tool. AI docs explain *how to modify* the codebase.
+| Audience | Location | Purpose |
+|----------|----------|---------|
+| **Humans** | `docs/` (mkdocs) | *How to use* — tutorials, visual guides |
+| **AI agents** | Docstrings, CLAUDE.md, ADRs | *How to modify* — dense, structured, co-located with code |
 
 ## Standardized Terminal Output
 
@@ -256,6 +262,17 @@ error("No geometry column (required)")     # ✗ Red X
 detail("Processing chunk 3/10...")         # Dimmed text
 ```
 
+## Design Principles
+
+| Principle | Meaning | ADR |
+|-----------|---------|-----|
+| **Don't duplicate** | Orchestrate libraries (geoparquet-io, rio-cogeo), never reimplement | — |
+| **YAGNI** | No speculative features; complexity is expensive | — |
+| **Interactive + automatable** | Every prompt has `--auto` fallback | — |
+| **versions.json is truth** | Drives sync, validation, history | [ADR-0005](context/shared/adr/0005-versions-json-source-of-truth.md) |
+| **Plugin interface early** | Handlers follow consistent interface for future plugins | [ADR-0003](context/shared/adr/0003-plugin-architecture.md) |
+| **CLI wraps API** | All logic in library; CLI is thin Click layer | [ADR-0007](context/shared/adr/0007-cli-wraps-api.md) |
+
 ## Tool Usage
 
 | Tool | Purpose | Documentation |

portolan_cli-0.1.3/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: portolan-cli
+Version: 0.1.3
+Summary: A CLI tool for managing cloud-native geospatial data
+Project-URL: Homepage, https://github.com/portolan-sdi/portolan-cli
+Project-URL: Bug Tracker, https://github.com/portolan-sdi/portolan-cli/issues
+Project-URL: Documentation, https://github.com/portolan-sdi/portolan-cli#readme
+Project-URL: Source, https://github.com/portolan-sdi/portolan-cli
+Author-email: Nissim Lebovits <nlebovits@pm.me>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: cloud-native,geospatial,gis,io
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Requires-Dist: click>=8.3.1
+Provides-Extra: dev
+Requires-Dist: bandit>=1.9.3; extra == 'dev'
+Requires-Dist: codespell>=2.4.1; extra == 'dev'
+Requires-Dist: commitizen>=4.13.4; extra == 'dev'
+Requires-Dist: hypothesis>=6.151.5; extra == 'dev'
+Requires-Dist: mutmut>=3.4.0; extra == 'dev'
+Requires-Dist: mypy>=1.19.1; extra == 'dev'
+Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.5.1; extra == 'dev'
+Requires-Dist: pytest-benchmark>=5.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3.1; extra == 'dev'
+Requires-Dist: pytest>=9.0.2; extra == 'dev'
+Requires-Dist: radon>=6.0.1; extra == 'dev'
+Requires-Dist: ruff>=0.14.11; extra == 'dev'
+Requires-Dist: vulture>=2.14; extra == 'dev'
+Requires-Dist: xenon>=0.9.3; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.7.1; extra == 'docs'
+Requires-Dist: mkdocs>=1.6.1; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=1.0.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="docs/assets/images/logo.svg" alt="Portolan Logo" width="200"/>
+  <h1>Portolan CLI</h1>
+  <p><strong>Cloud-native geospatial data catalogs, simplified</strong></p>
+</div>
+
+---
+
+A CLI for publishing and managing **cloud-native geospatial data catalogs**. Portolan orchestrates format conversion (GeoParquet, COG), versioning, and sync to object storage—no running servers, just static files.
+
+## Why Portolan?
+
+| Benefit | How |
+|---------|-----|
+| **Scalable** | Cloud object storage that scales to petabytes |
+| **Open** | 100% open source, open formats (GeoParquet, COG, STAC, Iceberg) |
+| **AI-Ready** | STAC metadata enables semantic search and LLM integration |
+| **Cheap** | Pay only for storage + egress — no servers to run |
+| **Sovereign** | Host anywhere (AWS, GCS, Azure, MinIO, Cloudflare R2) |
+| **Breaks the GIS silo** | Query with DuckDB, Snowflake, BigQuery, Databricks, Pandas — not just GIS tools |
+
+## What It Does
+
+- **Convert** vector/raster data to cloud-native formats (GeoParquet, COG)
+- **Generate** STAC catalogs with rich metadata, thumbnails, and MapLibre styles
+- **Version** datasets with checksums and history tracking
+- **Sync** to S3, GCS, Azure, or any S3-compatible storage
+
+## Quick Example
+
+```bash
+portolan init
+portolan dataset add census.parquet --title "Census 2022" --auto
+portolan remote add prod s3://my-bucket/catalog
+portolan sync
+```
+
+## Installation
+
+### Recommended: pipx (for global use)
+
+```bash
+pipx install portolan-cli
+```
+
+This installs `portolan` in an isolated environment while making the command globally available.
+
+If you don't have pipx installed:
+```bash
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+```
+
+### Alternative: pip
+
+```bash
+pip install portolan-cli
+```
+
+**Note:** This installs into your global or user site-packages and may conflict with other packages.
+
+### For Development
+
+Use [uv](https://github.com/astral-sh/uv) for local development:
+
+```bash
+git clone https://github.com/portolan-sdi/portolan-cli.git
+cd portolan-cli
+uv sync --all-extras
+uv run portolan --help
+```
+
+See [Contributing Guide](docs/contributing.md) for full development setup.
+
+## Documentation
+
+- [Contributing Guide](docs/contributing.md)
+- [Architecture](context/architecture.md)
+- [Roadmap](ROADMAP.md)
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE)

portolan_cli-0.1.3/README.md

@@ -0,0 +1,83 @@
+<div align="center">
+  <img src="docs/assets/images/logo.svg" alt="Portolan Logo" width="200"/>
+  <h1>Portolan CLI</h1>
+  <p><strong>Cloud-native geospatial data catalogs, simplified</strong></p>
+</div>
+
+---
+
+A CLI for publishing and managing **cloud-native geospatial data catalogs**. Portolan orchestrates format conversion (GeoParquet, COG), versioning, and sync to object storage—no running servers, just static files.
+
+## Why Portolan?
+
+| Benefit | How |
+|---------|-----|
+| **Scalable** | Cloud object storage that scales to petabytes |
+| **Open** | 100% open source, open formats (GeoParquet, COG, STAC, Iceberg) |
+| **AI-Ready** | STAC metadata enables semantic search and LLM integration |
+| **Cheap** | Pay only for storage + egress — no servers to run |
+| **Sovereign** | Host anywhere (AWS, GCS, Azure, MinIO, Cloudflare R2) |
+| **Breaks the GIS silo** | Query with DuckDB, Snowflake, BigQuery, Databricks, Pandas — not just GIS tools |
+
+## What It Does
+
+- **Convert** vector/raster data to cloud-native formats (GeoParquet, COG)
+- **Generate** STAC catalogs with rich metadata, thumbnails, and MapLibre styles
+- **Version** datasets with checksums and history tracking
+- **Sync** to S3, GCS, Azure, or any S3-compatible storage
+
+## Quick Example
+
+```bash
+portolan init
+portolan dataset add census.parquet --title "Census 2022" --auto
+portolan remote add prod s3://my-bucket/catalog
+portolan sync
+```
+
+## Installation
+
+### Recommended: pipx (for global use)
+
+```bash
+pipx install portolan-cli
+```
+
+This installs `portolan` in an isolated environment while making the command globally available.
+
+If you don't have pipx installed:
+```bash
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+```
+
+### Alternative: pip
+
+```bash
+pip install portolan-cli
+```
+
+**Note:** This installs into your global or user site-packages and may conflict with other packages.
+
+### For Development
+
+Use [uv](https://github.com/astral-sh/uv) for local development:
+
+```bash
+git clone https://github.com/portolan-sdi/portolan-cli.git
+cd portolan-cli
+uv sync --all-extras
+uv run portolan --help
+```
+
+See [Contributing Guide](docs/contributing.md) for full development setup.
+
+## Documentation
+
+- [Contributing Guide](docs/contributing.md)
+- [Architecture](context/architecture.md)
+- [Roadmap](ROADMAP.md)
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE)

portolan_cli-0.1.3/ROADMAP.md

@@ -0,0 +1,252 @@
+# Portolan Ecosystem Roadmap
+
+## Vision
+
+Portolan makes it easy to publish and consume cloud-native geospatial data. The ecosystem includes a spec, CLI, format plugins, a QGIS plugin, and a global data bootstrapper—each designed to work standalone or together.
+
+Development is **spec-driven but implementation-informed**: the [Portolan Spec](https://github.com/portolan-sdi/portolan-spec) evolves alongside the CLI.
+
+---
+
+## Phase 1: Core CLI + Spec
+
+The foundation. A complete, working CLI with Python API underneath.
+
+### Epic: Dataset Lifecycle
+
+Convert files to cloud-native formats, manage metadata, organize into a local catalog. Vector conversion uses [geoparquet-io](https://github.com/geoparquet/geoparquet-io).
+
+| Capability | Description |
+|------------|-------------|
+| `portolan init` | Create `.portolan/` catalog structure |
+| `portolan dataset add` | Detect format → convert (GeoParquet/COG) → extract metadata → stage |
+| `portolan dataset remove` | Remove datasets from catalog |
+| `portolan dataset list/info` | Catalog exploration |
+| Interactive + `--auto` | Works for humans and agents |
+
+### Epic: Cloud Sync
+
+Push catalogs to object storage. Portolan owns the bucket contents.
+
+| Capability | Description |
+|------------|-------------|
+| `portolan remote add/list` | Configure S3, GCS, Azure backends |
+| `portolan sync` | Push `.portolan/` to remote |
+| `versions.json` | Version history, checksums, sync state |
+
+### Epic: Validation & Repair
+
+Ensure catalogs meet the Portolan spec. Detect and fix drift.
+
+| Capability | Description |
+|------------|-------------|
+| `portolan check` | Validate local catalog against spec |
+| `portolan check --remote` | Detect drift (external edits to bucket) |
+| `portolan repair` | Re-sync remote from local truth |
+| `portolan prune` | Clean up old versions |
+| Actionable output | Specific guidance, not just pass/fail |
+
+### Epic: Styling & Thumbnails
+
+Make datasets visually browsable.
+
+| Capability | Description |
+|------------|-------------|
+| `style.json` | MapLibre-compatible style definitions |
+| Thumbnail generation | Auto-render preview images |
+| Smart defaults | Infer styles from data characteristics |
+
+### Epic: PMTiles Generation
+
+Generate vector tile overviews from GeoParquet datasets using [gpio-pmtiles](https://github.com/geoparquet-io/gpio-pmtiles).
+
+| Capability | Description |
+|------------|-------------|
+| PMTiles as derivative | Generated from GeoParquet for web display |
+| Automatic on `dataset add` | Optional; controlled by flag or config |
+| Stored alongside source | Part of the dataset, not a separate dataset |
+
+**Note:** PMTiles are a *view* of the data for rendering, not the source of truth. GeoParquet remains the canonical format. (PMTiles *could* be added as standalone datasets, but the primary use case is as overviews.)
+
+### Epic: COPC Support
+
+Cloud-optimized point clouds for LiDAR and similar data.
+
+| Capability | Description |
+|------------|-------------|
+| COPC conversion | Convert point cloud formats to COPC |
+| Metadata extraction | Bounds, point count, CRS |
+| Styling conventions | Point cloud visualization defaults |
+
+### Epic: Python API
+
+All functionality is implemented as a Python library; CLI wraps it.
+
+| Capability | Description |
+|------------|-------------|
+| `Catalog` class | `init()`, `add()`, `sync()`, `check()` |
+| Built simultaneously | API *is* the implementation; CLI is the interface |
+| Agent-friendly | Clear errors, predictable outputs |
+| `SKILLS.md` | LLM-optimized documentation |
+
+### Spec Evolution (Phase 1)
+
+The [Portolan Spec](https://github.com/portolan-sdi/portolan-spec) develops in lockstep:
+
+- Required metadata fields
+- Catalog structure and naming
+- Validation rules
+- Remote structure and versioning
+- PMTiles and COPC conventions
+
+---
+
+## Parallel: Iceberg Plugin
+
+Tabular analytics on geospatial data. Developed by Javier alongside Phase 1.
+
+| Capability | Description |
+|------------|-------------|
+| `portolan-iceberg` | Apache Iceberg tables alongside STAC |
+| Query integration | SQL/DataFrame access to versioned data |
+
+**Note:** Separate package, separate maintainer, but expected to land around the same time as Phase 1. STAC remains the catalog layer; Iceberg is the analytics layer.
+
+---
+
+## Phase 2: QGIS Plugin
+
+Bring Portolan catalogs into desktop GIS workflows.
+
+| Capability | Description |
+|------------|-------------|
+| Browse catalogs | Connect to Portolan remotes, explore datasets |
+| Pull data | Load GeoParquet/COG into QGIS layers |
+| Edit metadata | Update titles, descriptions, licenses |
+| Spec validation | Check datasets from within QGIS |
+
+**Dependency:** Phase 1 complete.
+
+---
+
+## Phase 3: Global Data Bootstrapper
+
+Subset global datasets to bootstrap local catalogs.
+
+| Capability | Description |
+|------------|-------------|
+| Source registry | Curated global datasets (Overture, ESA, etc.) |
+| Region extraction | Clip to bounding box or admin boundary |
+| One-command bootstrap | `portolan bootstrap --region "Nairobi"` |
+
+**Dependency:** Phase 1 complete.
+
+---
+
+## TBD: Access Control & Visibility
+
+Multi-tenant access control for teams sharing a Portolan catalog. Timing and scope to be determined.
+
+### Potential Capabilities
+
+| Capability | Description |
+|------------|-------------|
+| Visibility metadata | Mark datasets as `public` or `private` with optional tenant assignment |
+| User management | Create/list/remove users with credentials |
+| Access policies | Grant/revoke user access to specific dataset paths |
+| Policy enforcement | Integration with storage IAM (MinIO, S3, GCS) |
+
+### Open Questions
+
+- **Where does auth live?** Portolan is "static files only" — user management likely requires a sidecar service or delegation to storage provider IAM
+- **MinIO vs generic?** MinIO has rich policy APIs; S3/GCS use IAM. Do we abstract or specialize?
+- **Scope boundary:** Portolan may just *tag* visibility; enforcement happens at the storage layer
+
+### Example Workflow (Conceptual)
+
+```bash
+# Add a public dataset
+portolan dataset add satellite.parquet --visibility public
+
+# Add a private dataset for a tenant
+portolan dataset add confidential.parquet --visibility private --tenant acme
+
+# User management (if Portolan handles it)
+portolan user add analyst
+portolan access grant analyst acme/*
+```
+
+**See also:** [ADR-0006 (Remote Ownership Model)](https://github.com/portolan-sdi/portolan-cli/blob/main/context/shared/adr/0006-remote-ownership-model.md) — explains why multi-user collaboration is complex under the current ownership model.
+
+---
+
+## TBD: Data Consumption & SQL Engines
+
+Documentation and tooling for consuming Portolan catalogs from analytics engines. Timing to be determined.
+
+### Potential Capabilities
+
+| Capability | Description |
+|------------|-------------|
+| Consumption guides | How to query Portolan catalogs from popular engines |
+| Connection snippets | Copy-paste connection strings for each engine |
+| `portolan connect` | Generate connection config for a specific engine |
+
+### Target Engines
+
+| Engine | Protocol | Notes |
+|--------|----------|-------|
+| **DuckDB** | S3/HTTP | Native GeoParquet support |
+| **Snowflake** | External tables | Via stage or external access |
+| **BigQuery** | BigLake / external tables | GCS-native |
+| **Databricks** | Unity Catalog / S3 | Delta Lake interop via Iceberg |
+| **Trino/Presto** | Hive connector | S3-backed |
+| **Oracle** | External tables | Via object storage |
+| **Pandas/GeoPandas** | obstore / fsspec | Direct Python access |
+
+### Example: DuckDB
+
+```sql
+-- Configure S3 access
+SET s3_endpoint = 'storage.example.com';
+SET s3_access_key_id = 'analyst';
+SET s3_secret_access_key = '...';
+SET s3_use_ssl = true;
+
+-- Query a Portolan dataset directly
+SELECT * FROM 's3://catalog/public/census/census.parquet';
+
+-- Or with spatial filtering
+SELECT * FROM 's3://catalog/public/census/census.parquet'
+WHERE ST_Within(geometry, ST_GeomFromText('POLYGON((...))'));
+```
+
+### Why This Matters
+
+Portolan's value is "publish once, consume anywhere." Without consumption docs, users publish data but don't know how to use it. This closes the loop.
+
+---
+
+## Out of Scope for v1.0
+
+| Item | Reason |
+|------|--------|
+| 3D Tiles | Niche; can be community-contributed later |
+| Browser/Map UI | May be unnecessary with agentic workflows; revisit post-v1 |
+
+---
+
+## Summary
+
+| Phase | Scope | Timing |
+|-------|-------|--------|
+| **Phase 1** | Core CLI, Python API, Spec, PMTiles, COPC | Now |
+| **Parallel** | Iceberg Plugin (Javier) | Alongside Phase 1 |
+| **Phase 2** | QGIS Plugin | After Phase 1 |
+| **Phase 3** | Global Bootstrapper | After Phase 1 |
+| **TBD** | Access Control & Visibility | To be scoped |
+| **TBD** | Data Consumption & SQL Engines | To be scoped |
+
+---
+
+*Portolan is an open source project under [Radiant Earth](https://radiant.earth).*