mainsequence-metatable 0.1.5.dev6__tar.gz → 0.1.6.dev7__tar.gz

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/.agents/skills/client/metatables-local-development/SKILL.md

@@ -12,11 +12,11 @@ development fixtures and test writes in the local runtime, then return to the
 intended environment as part of the requested workflow. Respect an explicitly
 requested target or backend-specific test scope.
 
-In a copied skill, resolve the `docs/` and `examples/` paths below relative to
+In a copied skill, resolve the `docs/` and `src/metatables/examples/` paths below relative to
 this skill's `references/` directory. In the MetaTables source checkout, resolve
 them from the repository root. Read `docs/operations/local-runtime.md` for runtime
 selection and persistence, and `docs/client/installation-and-connection.md` when
-installing or troubleshooting. `examples/local_app/README.md` provides a complete
+installing or troubleshooting. `src/metatables/examples/local_app/README.md` provides a complete
 installed-package migration/write/read example.
 
 ## Select local storage deliberately

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/.agents/skills/client/metatables-meta-tables/SKILL.md

@@ -12,7 +12,7 @@ client. It covers application-facing models and workflows. Client-library
 implementation, this repository's development/release tooling, and API internals
 have separate ownership.
 
-In a copied skill, resolve the `docs/` and `examples/` paths below relative to
+In a copied skill, resolve the `docs/` and `src/metatables/examples/` paths below relative to
 this skill's `references/` directory. The client CLI bundles the matching version's
 guides and examples there, including their linked documents. In the MetaTables
 source checkout, read the same paths from the repository root.
@@ -51,7 +51,7 @@ contract. Preserve the user's existing authorization and scope.
   evolution.
 - Existing externally owned tables use `register_external_sqlalchemy_model` with
   their actual physical binding. Registration does not create the physical table;
-  see `docs/client/register-existing-tables.md` and `examples/external_table.py`.
+  see `docs/client/register-existing-tables.md` and `src/metatables/examples/external_table.py`.
 - `backend_managed` is a separate low-level API provisioning intent. Do not use it
   as a substitute for ordinary managed application-table migrations.
 
@@ -62,7 +62,7 @@ are fingerprints, not table identity. See `docs/concepts/identity-and-scope.md`.
 
 ## SQLAlchemy contract rules
 
-Use `examples/tables.py` as the tested pattern. Declare an explicit
+Use `src/metatables/examples/tables.py` as the tested pattern. Declare an explicit
 application-prefixed physical name with `schema_table_name(app, concept)`, a
 stable logical identifier, and an intention-rich `__metatable_description__`.
 Give columns useful `info={"label": ..., "description": ...}` metadata. Explain
@@ -84,7 +84,7 @@ revisions; do not recompute identity from columns or rewrite applied history.
 
 ## Queries and mutations
 
-Read `docs/client/query-and-mutate.md` and `examples/query.py`. Use
+Read `docs/client/query-and-mutate.md` and `src/metatables/examples/query.py`. Use
 `compile_sqlalchemy_statement` with bound parameters. The request sends SQL and
 selects one DataSource; the API executes as the authenticated user, and the
 selected database backend enforces Reader/Writer permissions on the tables

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/.agents/skills/client/metatables-migrations/SKILL.md

@@ -16,7 +16,7 @@ For upgrading older client imports, SQL scopes or provider integration, use the
 [legacy upgrade skill](../metatables-upgrade-legacy-app/SKILL.md). This skill
 covers authoring and running application schema revisions.
 
-In a copied skill, resolve the `docs/` and `examples/` paths below relative to
+In a copied skill, resolve the `docs/` and `src/metatables/examples/` paths below relative to
 this skill's `references/` directory. The client CLI bundles the matching version's
 guides and examples there, including their linked documents. In the MetaTables
 source checkout, read the same paths from the repository root.
@@ -28,7 +28,7 @@ verification within the requested scope.
 
 Read `docs/client/define-and-migrate-tables.md`,
 `docs/concepts/table-contracts-and-lifecycle.md`, and the tested
-`examples/tables.py`. Managed authoring is migration-first: define SQLAlchemy
+`src/metatables/examples/tables.py`. Managed authoring is migration-first: define SQLAlchemy
 models, select a provider, author and apply a revision with the client, then
 finalize catalog bindings through the API. Use the
 [table skill](../metatables-meta-tables/SKILL.md) for contract design.
@@ -106,7 +106,7 @@ and finalizes contracts through the API. Treat connection material as private.
 
 Use the application's setup entry point when available. Python code can call
 `metatables.upgrade_application("ledger.migrations:migration")`;
-`examples/scripts/setup_metatables.py` shows the pattern. Remove the retired
+`src/metatables/examples/scripts/setup_metatables.py` shows the pattern. Remove the retired
 `application_migration_providers` setting and use Python references instead of aliases.
 Application migration histories remain separate from API system migrations.
 

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/.agents/skills/client/metatables-time-index-table-updates/SKILL.md

@@ -12,7 +12,7 @@ client. It covers application-facing models and workflows. Client-library
 implementation, this repository's development/release tooling, and API internals
 have separate ownership.
 
-In a copied skill, resolve the `docs/` and `examples/` paths below relative to
+In a copied skill, resolve the `docs/` and `src/metatables/examples/` paths below relative to
 this skill's `references/` directory. The client CLI bundles the matching version's
 guides and examples there, including their linked documents. In the MetaTables
 source checkout, read the same paths from the repository root.
@@ -24,8 +24,8 @@ verification within the requested scope.
 
 Read `docs/client/build-an-updater.md`,
 `docs/concepts/time-index-tables-and-updates.md`, and the tested
-`examples/updater.py`. Use `docs/client/read-existing-time-index-tables.md` and
-`examples/reader.py` for consumers that only need existing output.
+`src/metatables/examples/updater.py`. Use `docs/client/read-existing-time-index-tables.md` and
+`src/metatables/examples/reader.py` for consumers that only need existing output.
 
 The storage contract is a `PlatformTimeIndexMetaTable` SQLAlchemy class. The
 producer is a `TimeIndexTableUpdater`; the API record is `TimeIndexTableUpdate`.
@@ -41,7 +41,7 @@ choices, first-run/backfill bounds, and whether identity must be preserved from
 the task and existing code. Clarify only unresolved choices that change the
 published contract. Keep storage description, namespace, identifier, cadence,
 columns, and FK/index metadata on the authoring model, not the updater config.
-Use intention-rich table and column descriptions; see `examples/tables.py`.
+Use intention-rich table and column descriptions; see `src/metatables/examples/tables.py`.
 
 Migrate and bind the output class before constructing the producer. Pass explicit
 `config` and `output_table`; do not create/register tables inside `update()`.

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/.agents/skills/client/metatables-upgrade-legacy-app/SKILL.md

@@ -14,7 +14,7 @@ in the MainSequence SDK.
 
 Read `docs/client/upgrade-legacy-app.md` for the conversion table and before/after
 repository compiler examples. In a copied skill, resolve the `docs/` and
-`examples/` paths here relative to this skill's `references/` directory. In the
+`src/metatables/examples/` paths here relative to this skill's `references/` directory. In the
 MetaTables source checkout, resolve them from the repository root.
 
 Use `docs/client/installation-and-connection.md` to establish the target package

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/MANIFEST.in

@@ -1,8 +1,9 @@
 include alembic.ini mkdocs.yml uv.lock compose.database-tests.yml
 include .mainsequence/workflows/metatables-api.yaml
-include api/metatables/configuration.yaml
+include api/metatables/main.py
+include src/metatables/api/metatables/configuration.yaml
 recursive-include docs *.md *.json *.py *.csv *.mako *.svg
-recursive-include examples *.md *.json *.py *.csv *.mako
+recursive-include src/metatables/examples *.md *.json *.py *.csv *.mako
 recursive-include scripts *.py
 recursive-include tests *.py *.json Dockerfile Dockerfile.dockerignore
 graft .agents/skills/client

{mainsequence_metatable-0.1.5.dev6/mainsequence_metatable.egg-info → mainsequence_metatable-0.1.6.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence-metatable
-Version: 0.1.5.dev6
+Version: 0.1.6.dev7
 Summary: Main Sequence MetaTables Python client and standalone API
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT
@@ -100,7 +100,7 @@ through Settings; startup never runs Alembic.
 The [documentation index](docs/index.md) separates client, API, operations, and
 contributor guides. The [capability reference](docs/reference/capabilities.md)
 records implemented and unavailable operations, including inherited methods and
-CLI commands. Runnable guide assets live in [examples](examples/README.md).
+CLI commands. Runnable guide assets live in [examples](src/metatables/examples/README.md).
 
 ## Client skills
 

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/README.md

@@ -45,7 +45,7 @@ through Settings; startup never runs Alembic.
 The [documentation index](docs/index.md) separates client, API, operations, and
 contributor guides. The [capability reference](docs/reference/capabilities.md)
 records implemented and unavailable operations, including inherited methods and
-CLI commands. Runnable guide assets live in [examples](examples/README.md).
+CLI commands. Runnable guide assets live in [examples](src/metatables/examples/README.md).
 
 ## Client skills
 

mainsequence_metatable-0.1.6.dev7/alembic.ini

@@ -0,0 +1,3 @@
+[alembic]
+script_location = src/metatables/api/backend/migrations
+

mainsequence_metatable-0.1.6.dev7/api/metatables/main.py

@@ -0,0 +1,5 @@
+"""Hosted workflow entrypoint; the server is installed as metatables.api."""
+
+from metatables.api.metatables.main import app
+
+__all__ = ["app"]

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/adr/api/0004-approved-application-migrations.md

@@ -50,7 +50,7 @@ remain explicit Settings operations.
 
 ## Example integration
 
-`examples/scripts/setup_metatables.py` only reserves, upgrades and finalizes the
+`src/metatables/examples/scripts/setup_metatables.py` only reserves, upgrades and finalizes the
 tutorial provider. Every data-dependent tutorial command calls it first. VS Code
 launches then seed instruments and run producers through `--prepare-data` before
 the requested example. Offline preview and endpoint-only connect skip preparation.

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/adr/api/0008-mysql-mssql-table-workflows.md

@@ -46,7 +46,7 @@ ownership and unknown-outcome reconciliation. Local verification is complete; ho
 
 `POST /data-sources/` accepts `mysql` and `mssql`, and validation opens their
 connections and runs `SELECT 1`. At the time of the original decision, the
-static feature registry declared no table support for either. The physical operations in `api/backend/integrations/`
+static feature registry declared no table support for either. The physical operations in `src/metatables/api/backend/integrations/`
 use PostgreSQL or SQLite connections, SQL and introspection; they cannot act on
 the registered MySQL or MSSQL source.
 
@@ -172,14 +172,14 @@ engine matrices in routes, Admin and documentation.
 
 Refactor the current SQLite and PostgreSQL paths into this contract before
 adding MySQL and MSSQL implementations. In particular, remove engine decisions
-from `api/app/bootstrap.py`, `api/app/routes/application_migrations.py`,
-`api/app/routes/table_sql.py`, `api/app/routes/runtime_context.py`, and
-`api/backend/integrations/source_validation.py`; route existing SQLite and
+from `src/metatables/api/app/bootstrap.py`, `src/metatables/api/app/routes/application_migrations.py`,
+`src/metatables/api/app/routes/table_sql.py`, `src/metatables/api/app/routes/runtime_context.py`, and
+`src/metatables/api/backend/integrations/source_validation.py`; route existing SQLite and
 PostgreSQL work through the bound backend in this first step, before implementing
 MySQL or MSSQL table support. During the refactor, retain the existing MySQL/MSSQL
 connection probes without pretending they satisfy the full backend contract.
 Move the branches in `postgresql_*`
-physical helpers and `api/backend/database_operations/runtime.py` into adapter
+physical helpers and `src/metatables/api/backend/database_operations/runtime.py` into adapter
 implementations or shared engine-neutral helpers. This refactor must preserve
 current SQLite and PostgreSQL behavior under the existing contract tests. It
 prevents the new engines from multiplying conditionals across every endpoint.

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/adr/api/0010-import-external-tables-and-views.md

@@ -60,10 +60,10 @@ explicitly identified as belonging to the Vite application.
 
 | Area | Current evidence | Required change |
 | --- | --- | --- |
-| HTTP workflow | Generated OpenAPI has `POST /meta-tables/register/` and `POST /meta-tables/{uid}/introspect/`, but no import action. `api/app/routes/table_registration.py` requires one caller-authored contract. | One import operation with discovery, preview, selection, reconciliation, and structured results. |
-| Discovery | `TableBackend` in `api/backend/backends/contracts.py` introspects a known name. It has no relation discovery or batch introspection contract. | Add narrow discovery and read operations to this existing facet. |
+| HTTP workflow | Generated OpenAPI has `POST /meta-tables/register/` and `POST /meta-tables/{uid}/introspect/`, but no import action. `src/metatables/api/app/routes/table_registration.py` requires one caller-authored contract. | One import operation with discovery, preview, selection, reconciliation, and structured results. |
+| Discovery | `TableBackend` in `src/metatables/api/backend/backends/contracts.py` introspects a known name. It has no relation discovery or batch introspection contract. | Add narrow discovery and read operations to this existing facet. |
 | External source resolution | `CatalogDataSourceProvider.get()` calls `RuntimeStorageBinding.require_execution_source()`. A saved non-runtime source cannot be used by table operations. | Resolve sources according to the authorized operation; preserve the runtime restriction for managed DDL, migrations, and caller-written SQL. |
-| Restart invariants | `RuntimeBootstrap.inspect()` in `api/app/bootstrap.py` rejects any `MetaTable` or `PhysicalOperation` referencing another source. | Permit externally owned MetaTables on registered sources, while keeping physical mutation journals and managed tables bound to the runtime source. |
+| Restart invariants | `RuntimeBootstrap.inspect()` in `src/metatables/api/app/bootstrap.py` rejects any `MetaTable` or `PhysicalOperation` referencing another source. | Permit externally owned MetaTables on registered sources, while keeping physical mutation journals and managed tables bound to the runtime source. |
 | View access | `postgresql_access.py` and `sqlite_access.py` require ordinary tables. `hosted.py` rejects MySQL objects other than base tables and MSSQL objects other than user tables. | Explicit view admission and read semantics. Changing an introspection query alone is insufficient. |
 | Physical metadata | `MetaTable.kind` distinguishes relational and time-index tables. Contract normalization preserves extra physical fields but does not validate `relation_kind` as a first-class invariant. | Validate physical relation kind independently of the existing logical kind. A view is a relational MetaTable. |
 | Names and types | `catalog_rules.py` and `table_contracts.py` impose an unqualified 63-character table-name rule; `models.py` stores `String(63)`. Some type validation retains PostgreSQL assumptions. | Preserve legal external identifiers and native types through adapter normalization, without truncation or executing catalog expressions. |
@@ -118,7 +118,7 @@ generic capability registry is introduced.
 ### 2. Extend the existing backend contract
 
 Add these conceptual operations to `DatabaseBackend.tables` in
-`api/backend/backends/contracts.py`; retain `backend_for(source)` as the only
+`src/metatables/api/backend/backends/contracts.py`; retain `backend_for(source)` as the only
 engine dispatch point:
 
 ```text
@@ -556,11 +556,11 @@ availability.
 
 ## Implementation and verification record
 
-- Shared orchestration: `api/backend/operations/import_relations.py`; engine
+- Shared orchestration: `src/metatables/api/backend/operations/import_relations.py`; engine
   discovery, read-only sessions and safe runtime-view validation:
-  `api/backend/backends/relation_tables.py`, selected by the existing registry.
-- Published commands/results: `api/backend/contracts/relation_import.py` and
-  `api/app/routes/table_import.py`. Existing introspect handles Writer refresh.
+  `src/metatables/api/backend/backends/relation_tables.py`, selected by the existing registry.
+- Published commands/results: `src/metatables/api/backend/contracts/relation_import.py` and
+  `src/metatables/api/app/routes/table_import.py`. Existing introspect handles Writer refresh.
 - Migration `0007_external_relation_names` widens hosted physical names to 128
   characters. SQLite retains its descriptive legacy VARCHAR width without a table
   rebuild; SQLite does not enforce that width. Missing relation kinds read as table.

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/adr/api/0013-application-owned-migrations.md

@@ -80,7 +80,7 @@ dropped tables. Revision files already applied remain immutable.
 
 ## MetaTables system migrations
 
-The API continues to own `api.backend.migrations`, `metatables_catalog_version`
+The API continues to own `metatables.api.backend.migrations`, `metatables_catalog_version`
 and the explicit admin bootstrap/upgrade operation in Settings. Application
 migration commands do not invoke that operation. Applications must keep their
 physical names and version tables separate from reserved system objects.

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/adr/client/0011-cli-local-development-with-managed-admin.md

@@ -10,6 +10,11 @@ Date: 2026-09-30
 
 Status: Accepted.
 
+Amended 2026-10-01 (MetaTables #11): `METATABLES_API_URL` selects only a loopback
+development API. Hosted clients resolve their SDK-owned Environment's deployment
+automatically under amended ADR 0003. Document both CLI and Python selection;
+`--local` and `configure_local_client()` continue configuring the URL automatically.
+
 Amended 2026-10-01: both SDK session sources use the developer's saved session
 from the machine's credential store, which the Main Sequence CLI and the VS Code
 extension share. The API process receives only its backend and reads that
@@ -42,7 +47,7 @@ Vite already proxies `/api` and the frontend already supports direct access in
 development mode. This is the local runtime to expose through the installed CLI.
 
 The remaining setup assumes two manually prepared source checkouts. The launcher
-requires `api/app/main.py` inside its backend directory and a pre-existing Admin
+requires `src/metatables/api/app/main.py` inside its backend directory and a pre-existing Admin
 `node_modules` directory. The installed CLI starts only the API. System bootstrap
 and application-owned migrations also need supported client commands.
 
@@ -137,8 +142,9 @@ ownership, permissions, loopback target and current launcher identity, and uses
 the API's existing Git/runtime checks. An absent, stale or mismatched local
 connection produces a local launch error; it never falls back to hosted discovery.
 The explicit local selection applies to the operation scope in the CLI and the
-configured Python process. Other invocations retain ADR 0003's existing endpoint
-precedence, including `METATABLES_API_URL` and hosted discovery.
+configured Python process. Other invocations use ADR 0003's Environment-scoped
+hosted discovery unless a loopback development URL is configured. A hosted URL
+in `METATABLES_API_URL` is rejected; it cannot override Environment selection.
 
 For execution and authoring, `--provider ledger.migrations:migration` resolves in
 the application's Python environment. The selected API supplies its environment
@@ -200,7 +206,7 @@ SDK authentication and API identity refresh requirements still apply.
 
 Move reusable combined-launch orchestration into the installed Python package.
 Both the public CLI and the existing VS Code developer launch should use it.
-Validate importable API modules instead of requiring `api/app/main.py` inside the
+Validate importable API modules instead of requiring `src/metatables/api/app/main.py` inside the
 consuming application. Reuse the current supervisor and private connection-file
 mechanism rather than creating a second independent runtime lifecycle.
 

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/client/build-an-updater.md

@@ -18,7 +18,7 @@ ad hoc storage definition inside `update()`.
 ```python
 from datetime import datetime, timezone
 from uuid import UUID
-from examples.updater import BalanceConfig, run
+from metatables.examples.updater import BalanceConfig, run
 
 run(BalanceConfig(
     account_uid=UUID("your-existing-account-uuid"),

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/client/query-and-mutate.md

@@ -13,7 +13,7 @@ the database applies your Reader and Writer grants to every table it touches.
 [The query example](../examples/query.py) selects account rows by name:
 
 ```python
-from examples.query import find_accounts
+from metatables.examples.query import find_accounts
 
 result = find_accounts("runtime-data-source-uuid", "Savings")
 ```

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/client/quickstart.md

@@ -4,7 +4,7 @@ Start with an existing table you can view. Complete [installation and
 connection](installation-and-connection.md), then run:
 
 ```bash
-python -m examples.quickstart TABLE_UID
+python -m metatables.examples.quickstart TABLE_UID
 ```
 
 The [example](../examples/quickstart.py) retrieves the resource through

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/client/read-existing-time-index-tables.md

@@ -9,7 +9,7 @@ identity, existing MetaTable object, or update resource.
 
 ```python
 from datetime import datetime, timezone
-from examples.reader import balances
+from metatables.examples.reader import balances
 
 frame = balances(
     "balance-table-uuid", "account-uuid",

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/client/tutorial.md

@@ -5,7 +5,7 @@ an instrument table and three time-index tables, load recorded prices, calculate
 daily returns and rolling volatility, and read published results independently.
 Choose different execution roots and inspect successes and simulated failures.
 
-The complete code is in [examples/tutorial](../examples/tutorial/README.md).
+The complete code is in [src/metatables/examples/tutorial](../examples/tutorial/README.md).
 Run commands from the MetaTables repository root in the Python environment where
 [MetaTables and the compatible SDK](installation-and-connection.md) are installed.
 The sample contains recorded SPY, QQQ, and IWM prices; a symbol is simply the key
@@ -14,7 +14,7 @@ identifying one instrument. No market-data service is needed for this exercise.
 ## 1. Preview the data
 
 ```bash
-python -m examples.tutorial preview
+python -m metatables.examples.tutorial preview
 ```
 
 This command needs no API connection. Expect `Recorded prices: 69 rows` and
@@ -27,7 +27,7 @@ dates per symbol. A return needs a preceding price, so each symbol has 22 return
 and calculates each symbol's change independently:
 
 ```python
-from examples.tutorial.frames import daily_returns, recorded_prices, rolling_volatility
+from metatables.examples.tutorial.frames import daily_returns, recorded_prices, rolling_volatility
 
 prices = recorded_prices()
 returns = daily_returns(prices)
@@ -86,11 +86,11 @@ These are system migrations only. The tutorial's application migrations run
 in the application's Python process through the client in both modes:
 
 ```bash
-python -m examples.scripts.setup_metatables --development-client .local/development-client.json
+python -m metatables.examples.scripts.setup_metatables --development-client .local/development-client.json
 ```
 
 Omit `--development-client` to use hosted deployment discovery. The application
-process loads `examples.tutorial.migrations:migration` and uses the selected
+process loads `metatables.examples.tutorial.migrations:migration` and uses the selected
 runtime's environment connection. The API needs no tutorial provider installation
 or configuration. The script reserves missing catalog bindings, applies outstanding
 Alembic revisions locally, and finalizes tables. It does not seed rows or run producers.
@@ -113,7 +113,7 @@ tutorial code so it loads the updated provider before setup.
 ## 4. Seed the instrument table
 
 ```bash
-python -m examples.tutorial seed
+python -m metatables.examples.tutorial seed
 ```
 
 Expect the three instrument rows. [operations.py](../examples/tutorial/operations.py)
@@ -127,8 +127,8 @@ Seed first because the three time-index tables' foreign keys require those symbo
 ## 5. Run the connected updaters
 
 ```bash
-python -m examples.tutorial update --root returns
-python -m examples.tutorial update --root volatility
+python -m metatables.examples.tutorial update --root returns
+python -m metatables.examples.tutorial update --root volatility
 ```
 
 [updaters.py](../examples/tutorial/updaters.py) contains three producers:
@@ -190,8 +190,8 @@ only once.
 ## 6. Read the result independently
 
 ```bash
-python -m examples.tutorial read --root returns --symbol SPY
-python -m examples.tutorial read --root volatility --symbol SPY
+python -m metatables.examples.tutorial read --root returns --symbol SPY
+python -m metatables.examples.tutorial read --root volatility --symbol SPY
 ```
 
 The reader resolves the published table by logical identifier and selects one
@@ -199,7 +199,7 @@ symbol. Without `--prepare-data`, it does not construct or execute an updater:
 
 ```python
 from metatables import TimeIndexTableRef
-from examples.tutorial.tables import RETURN_IDENTIFIER
+from metatables.examples.tutorial.tables import RETURN_IDENTIFIER
 
 reference = TimeIndexTableRef.from_identifier(RETURN_IDENTIFIER)
 frame = reference.get_df_between_dates(

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/concepts/architecture.md

@@ -64,7 +64,7 @@ also uses SQLAlchemy to describe the user's application tables.
 
 A user defines `class Account(PlatformManagedMetaTable, Base)` to author storage.
 After registration, `metatables.MetaTable` represents its HTTP resource. Inside
-the service, `api.backend.persistence.models.MetaTable` is the catalog ORM row.
+the service, `metatables.api.backend.persistence.models.MetaTable` is the catalog ORM row.
 They describe the same resource at different boundaries; they are not interchangeable.
 Client applications import `metatables`, not the API persistence models.
 

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/contributing/architecture-and-boundaries.md

@@ -1,17 +1,25 @@
 # Architecture and dependency boundaries
 
 The distribution has two public surfaces. `src/metatables` is the installed
-client, authoring helpers, migrations, updaters, and readers. `api` is the HTTP service, catalog, domain rules, and physical storage
-operations. Client applications import `metatables`.
+client, authoring helpers, migrations, updaters, and readers. `src/metatables/api`
+contains the HTTP service, catalog, domain rules, and physical storage operations.
+Client applications import `metatables`; server modules use `metatables.api` and
+bundled examples use `metatables.examples`. Package discovery is restricted to
+`src`, so the wheel owns only the `metatables` top-level package.
+
+`api/metatables/main.py` is a file entrypoint for the platform deployment workflow.
+It imports the namespaced server and is omitted from the wheel. There are no
+top-level `api` or `examples` compatibility packages: applications can own those
+names independently, including when they launch the installed MetaTables CLI.
 
 | Directory | Owns |
 | --- | --- |
-| `api/app` | FastAPI routes, dependency wiring, HTTP errors, local launcher admission. |
-| `api/backend/domain` and `contracts` | Storage access constraints, lifecycle, permission decisions, payload normalization. |
-| `api/backend/persistence` | Catalog ORM, queries, grants, membership, journals, update state. |
-| `api/backend/integrations` | SDK adapters and physical operations with PostgreSQL and SQLite communication adapters. |
-| `api/backend/backends` | DatabaseBackend contract, engine registry, catalog, table and SQL implementations. |
-| `api/backend/migrations` | Catalog schema history. |
+| `src/metatables/api/app` | FastAPI routes, dependency wiring, HTTP errors, local launcher admission. |
+| `src/metatables/api/backend/domain` and `contracts` | Storage access constraints, lifecycle, permission decisions, payload normalization. |
+| `src/metatables/api/backend/persistence` | Catalog ORM, queries, grants, membership, journals, update state. |
+| `src/metatables/api/backend/integrations` | SDK adapters and physical operations with PostgreSQL and SQLite communication adapters. |
+| `src/metatables/api/backend/backends` | DatabaseBackend contract, engine registry, catalog, table and SQL implementations. |
+| `src/metatables/api/backend/migrations` | Catalog schema history. |
 | `src/metatables/models.py` | API resource clients and MetaTables-specific DataSource behavior. |
 | `src/metatables/migrations` | Application provider lifecycle and scoped Alembic access. |
 | `src/metatables/updaters` | Producer execution and configuration hashing. |

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/contributing/documentation.md

@@ -22,7 +22,7 @@ decisions in the SDK repository.
 
 1. Update behavior and relevant tests together.
 2. Update the authored concept/workflow pages and the capability inventory.
-3. Keep runnable examples in `examples/` and exercise them in `tests/examples`.
+3. Keep runnable examples in `src/metatables/examples/` and exercise them in `tests/examples`.
 4. Regenerate references and check links, imports, examples, and the site.
 
 ```bash
@@ -38,7 +38,7 @@ The reference generator derives HTTP paths and schemas from `create_app`, Python
 exports from `metatables.__all__`, and CLI arguments from Typer. Capability status
 is maintained deliberately in the inventory because reflection cannot establish
 behavioral support. The generator also publishes copies of tested example assets
-inside the documentation site; edit their originals in `examples/`.
+inside the documentation site; edit their originals in `src/metatables/examples/`.
 
 The test suite rejects stale generated artifacts. The documentation checker
 validates local Markdown links, heading links, Python-block syntax, and skill

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/contributing/testing.md

@@ -84,7 +84,7 @@ referenced behavior tests. A route listing is not a substitute for executing the
 test. Signature and database-operation contracts live beside it; documentation is
 not used as a test fixture store.
 
-`tests/examples` executes the assets in `examples/`. Contract construction,
+`tests/examples` executes the assets in `src/metatables/examples/`. Contract construction,
 bound SQL, incremental frame shape, and SQLite persistence run without an API.
 A PostgreSQL example test also creates the authored relations, persists producer
 rows, and executes the compiled bound query in the disposable database. Network

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/examples/README.md

@@ -21,7 +21,7 @@ For one connected walkthrough, start with the [market tutorial](tutorial/README.
 
 ```bash
 python -m pytest -q tests/examples
-python -m examples.quickstart TABLE_UID
+python -m metatables.examples.quickstart TABLE_UID
 ```
 
 The [managed-table guide](../client/define-and-migrate-tables.md) explains how

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/examples/data_sources/README.md

@@ -14,7 +14,7 @@ They create a catalog registration; they do not provision a database.
 4. Run the script with your edited file:
 
 ```sh
-python examples/data_sources/register.py /path/to/my-source.json --validate
+python src/metatables/examples/data_sources/register.py /path/to/my-source.json --validate
 ```
 
 Each run creates a registration. Omit `--validate` to register without connecting.

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/examples/local_app/README.md

@@ -24,8 +24,8 @@ In another terminal in the same project and Python environment:
 ```bash
 metatables --local runtime status
 metatables --local runtime initialize
-metatables --local migrations upgrade --provider examples.local_app.migrations:migration
-python -m examples.local_app
+metatables --local migrations upgrade --provider metatables.examples.local_app.migrations:migration
+python -m metatables.examples.local_app
 metatables --local meta-table list
 ```
 
@@ -41,7 +41,7 @@ selected dialect, upserts one note, and reads it back. Ordinary reads and writes
 the existing row before any write:
 
 ```bash
-python -m examples.local_app --read-only
+python -m metatables.examples.local_app --read-only
 ```
 
 The API retains its selected database across restarts and branches. Initialization

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/examples/local_app/__main__.py

@@ -1,4 +1,4 @@
-"""Run with python -m examples.local_app from your application's Git checkout."""
+"""Run with python -m metatables.examples.local_app from your application's Git checkout."""
 
 import json
 
@@ -8,9 +8,9 @@ from metatables import configure_local_client
 def write_and_read(*, write: bool = True):
     from sqlalchemy import MetaData, select
 
-    from examples.local_app.tables import Note
     from metatables import MetaTable
     from metatables.compiled_sql.v1 import compile_sqlalchemy_statement, dialect_insert
+    from metatables.examples.local_app.tables import Note
 
     resource = MetaTable.get(identifier=Note.__metatable_identifier__)
     table = Note.__table__.to_metadata(MetaData(), schema=resource.physical_schema,

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/examples/local_app/migrations/__init__.py

@@ -1,6 +1,6 @@
 """Only this application's note table belongs to this application-owned provider."""
 
-from examples.local_app.tables import Base, Note
+from metatables.examples.local_app.tables import Base, Note
 from metatables.migrations import (
     build_alembic_version_metatable,
     build_metatable_migration_provider,
@@ -13,9 +13,9 @@ Version = build_alembic_version_metatable(
     table_name='metatables_local_example__alembic_version',
 )
 migration = build_metatable_migration_provider(
-    package='examples.local_app', migration_namespace='metatables_local_example',
-    script_location='examples.local_app.migrations:',
-    version_location_prefix='examples.local_app.migrations:versions',
+    package='metatables.examples.local_app', migration_namespace='metatables_local_example',
+    script_location='metatables.examples.local_app.migrations:',
+    version_location_prefix='metatables.examples.local_app.migrations:versions',
     target_metadata=Base.metadata, alembic_registry=Version,
     metatable_models=build_metatable_model_registry([Note], base=Base),
 )

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/examples/local_app/migrations/env.py

@@ -1,4 +1,4 @@
-from examples.local_app.migrations import migration
+from metatables.examples.local_app.migrations import migration
 from metatables.migrations.env import run_mainsequence_alembic_env
 
 run_mainsequence_alembic_env(default_provider=migration)

{mainsequence_metatable-0.1.5.dev6 → mainsequence_metatable-0.1.6.dev7}/docs/examples/scripts/setup_metatables.py

@@ -10,7 +10,7 @@ def setup_metatables():
 
     with api_endpoint_scope():
         print(f"Preparing tutorial on MetaTables API: {resolve_api_endpoint().url}", flush=True)
-        result = upgrade_application('examples.tutorial.migrations:migration', timeout=120)
+        result = upgrade_application('metatables.examples.tutorial.migrations:migration', timeout=120)
         print(f"Tutorial DataSource: {result['data_source_uid']}; revision: {result['revision']} "
               f"({'migrated' if result['migrated'] else 'already current'})", flush=True)
         return result
@@ -22,7 +22,7 @@ def main():
                         help="Use the private connection from the running local API/Admin launcher")
     args = parser.parse_args()
     if args.development_client:
-        from api.app.development_client import configure_development_client
+        from metatables.api.app.development_client import configure_development_client
 
         configure_development_client(args.development_client)
     setup_metatables()