pyaccesskit 0.1.0__tar.gz

pyaccesskit-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+site/
+
+# Virtual environments (incl. the optional x86 env used for in-process DAO tests)
+.venv/
+.venv-*/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Microsoft Access lock files and scratch databases
+*.laccdb
+*.ldb
+examples/out/
+scratch/

pyaccesskit-0.1.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/) (0.x releases may contain breaking changes, which are listed
+under **Changed**).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-26
+
+First release.
+
+### Added
+
+- **Lifecycle.** `AccessDatabase.create()` (atomic by default) and `AccessDatabase.open()` (read-only and
+  shared, exclusive, password), used as context managers. Guaranteed cleanup, with cleanup failures
+  attached as notes to the original exception. `db.raw` escape hatch with revocable proxies.
+- **Engines.** In-process DAO, Access-hosted DAO, and Access design sessions. `engine="auto"` selects one
+  and switches to a design session on the first design feature. Bitness-aware diagnostics.
+- **Process safety.** Access is always started as a new instance and never attached to. Process identity is
+  PID, creation time and image. Kill-on-close job objects, an ownership ledger with `reap_orphans()` /
+  `pyaccesskit cleanup`, a dialog watchdog (`AccessDialogError`), per-call timeouts, and Ctrl+C handling.
+- **Tables.** Short Text, Long Text, Number (all field sizes), Decimal, Currency, AutoNumber (incrementing
+  or Replication ID), Date/Time, Yes/No, Hyperlink and OLE Object columns. Literal and `Expr` defaults,
+  validation rules, captions, formats and input masks. Indexes (composite, descending, unique, primary).
+  Add, drop and rename columns and indexes, rename and drop tables, property bags. `Table.to_spec()`
+  round-trips to the normalized spec.
+- **Relationships.** Single and composite keys, referential integrity, cascades and join types, with
+  pre-validation of tables, columns, types and unique indexes.
+- **Queries and data.** Saved and pass-through queries, query kinds and parameters, and
+  `execute()`/`fetch_all()` with parameters bound by name.
+- **Forms** (provisional). Labels, text boxes, check boxes, combo boxes and buttons. Stacked and tabular
+  layouts, VBA event procedures, form properties, atomic build-then-swap replacement, `check_opens()` and
+  `controls()`.
+- **VBA modules** (provisional). Standard and class modules; read and replace code.
+- **Text import/export** (provisional). `SaveAsText`/`LoadFromText` for forms, reports, macros, queries and
+  modules, with the correct encoding per object type; files are UTF-8.
+- **Specs.** Immutable, serializable Pydantic models (`TableSpec`, `Column.*`, `IndexSpec`,
+  `RelationshipSpec`, `QuerySpec`, `FormSpec`) with JSON Schema. `Length` units (`cm`, `mm`, `inch`, `pt`,
+  `twips`).
+- **Errors.** A typed exception hierarchy with Access/DAO error numbers and `DBEngine.Errors` details.
+- **CLI.** `pyaccesskit doctor [--json] [--probe]`, `pyaccesskit inspect DB [--json] [--counts]` and
+  `pyaccesskit cleanup [--dry-run] [--json]`. `python -m pyaccesskit`.
+- **Diagnostics.** `pyaccesskit.diagnose()`.
+- **For AI agents.** `pyaccesskit guide` prints a version-matched guide (rules, API cheat sheet, SQL dialect
+  notes, error table, limits, and a complete tested example); `pyaccesskit schema` prints JSON Schemas of the
+  specs; the documentation site publishes `llms.txt` and `llms-full.txt`.
+- **Documentation.** Recipes, error / data-type / CLI references, FAQ, and an API reference generated from
+  the docstrings.
+
+### Fixed (found while documenting)
+
+- Opening a database for design no longer runs its `StartUpForm` (which could raise dialogs with code
+  disabled); the setting is preserved.
+- `bytes` query parameters are declared as `LongBinary`, so OLE Object data is no longer corrupted; binary
+  values read back as `bytes`.
+
+[Unreleased]: https://github.com/ariedotcodotnz/PyAccessKit/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ariedotcodotnz/PyAccessKit/releases/tag/v0.1.0

pyaccesskit-0.1.0/LICENSE

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

pyaccesskit-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: pyaccesskit
+Version: 0.1.0
+Summary: A modern, typed, Pythonic toolkit for building and modifying Microsoft Access databases and applications.
+Project-URL: Homepage, https://github.com/ariedotcodotnz/PyAccessKit
+Project-URL: Documentation, https://ariedotcodotnz.github.io/PyAccessKit/
+Project-URL: Changelog, https://github.com/ariedotcodotnz/PyAccessKit/blob/HEAD/CHANGELOG.md
+Project-URL: Issues, https://github.com/ariedotcodotnz/PyAccessKit/issues
+Project-URL: Source, https://github.com/ariedotcodotnz/PyAccessKit
+Author: Arie Joe
+License-Expression: MIT
+License-File: LICENSE
+Keywords: accdb,access,automation,com,dao,database,microsoft-access,pywin32
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pywin32>=306; sys_platform == 'win32'
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# PyAccessKit
+
+A modern, typed, Pythonic toolkit for building and modifying Microsoft Access databases (`.accdb`) and,
+progressively, whole Access applications without raw `pywin32` calls, DAO magic numbers or orphaned
+`MSACCESS.EXE` processes.
+
+```python
+from pyaccesskit import AccessDatabase, Column, Expr, Vba, cm
+
+with AccessDatabase.create("crm.accdb") as db:
+    db.tables.create(
+        "Customers",
+        columns=[
+            Column.autonumber("CustomerID", primary_key=True),
+            Column.text("CustomerName", length=200, required=True),
+            Column.text("Email", length=255, unique=True),
+            Column.date_time("CreatedAt", default=Expr("Now()")),
+        ],
+    )
+    db.tables.create(
+        "Orders",
+        columns=[
+            Column.autonumber("OrderID", primary_key=True),
+            Column.number("CustomerID", required=True),  # Long Integer, as in Access
+            Column.currency("Total", default=0),
+        ],
+    )
+    db.relationships.create("Customers.CustomerID", "Orders.CustomerID", cascade_delete=True)
+    db.queries.create("qryCustomers", "SELECT * FROM Customers ORDER BY CustomerName;")
+
+    with db.forms.create("frmCustomers", record_source="Customers", caption="Customers") as form:
+        form.textbox("CustomerName", label="Customer name", width=cm(8))
+        form.textbox("Email")
+        form.button("cmdClose", caption="Close", on_click=Vba("DoCmd.Close acForm, Me.Name"))
+```
+
+When the `with` block ends, the database file appears at `crm.accdb`, and any Access process PyAccessKit
+started is closed. If the block raises, no file is created and nothing is left running.
+
+> **Status:** alpha (`0.1.0`). The API may still change between 0.x releases.
+
+## Installation
+
+```console
+pip install pyaccesskit
+```
+
+Requirements:
+
+- Windows 10 or 11 and CPython 3.11–3.14 (64- or 32-bit; free-threaded builds are not supported).
+- Microsoft Access 2016 or later, including Microsoft 365. Alternatively, the Microsoft 365 Access Runtime
+  with a Python of the same bitness, for schema and data work only.
+
+Check your machine with:
+
+```console
+pyaccesskit doctor          # which engines work here, and why not
+pyaccesskit doctor --probe  # also builds a scratch database end to end
+```
+
+The spec models (`TableSpec`, `Column`, `FormSpec`, units, layout…) are pure Python and also import on
+Linux and macOS, so you can validate specs in CI without Access.
+
+## What you can do in 0.1
+
+| Area | Highlights | Stability |
+|---|---|---|
+| Lifecycle | Atomic `create()`, `open()` (read-only/shared, exclusive, password), guaranteed cleanup, `db.raw` escape hatch | stable-track |
+| Tables | Every common column type, defaults as Python values or `Expr`, validation rules, captions, formats, input masks; indexes (composite, descending, unique, primary); add, drop and rename columns and indexes; `to_spec()` round-trips | stable-track |
+| Relationships | Single and composite keys, referential integrity, cascades, join types, all checked before Access sees them | stable-track |
+| Queries & data | Saved queries (select, action, union, crosstab, pass-through), parameters bound by name, `execute()` / `fetch_all()` | stable-track |
+| Forms | Labels, text boxes, check boxes, combo boxes and buttons; stacked or tabular layout; VBA event procedures; atomic build-then-swap replacement | provisional |
+| Modules & text I/O | Standard and class modules; `SaveAsText`/`LoadFromText` for forms, reports, macros, queries and modules, stored as UTF-8 | provisional |
+| Decimal columns | `Column.decimal(precision=…, scale=…)` via ADO DDL | provisional |
+
+Reports, linked tables, VBA references, and the declarative `build`/`plan`/`apply` workflow are planned
+(see the [roadmap](https://ariedotcodotnz.github.io/PyAccessKit/#roadmap)).
+
+## Engines
+
+PyAccessKit reaches the database in one of three ways and picks one for you (`engine="auto"`):
+
+| Engine | When | Notes |
+|---|---|---|
+| In-process DAO | Python and Office have the **same bitness** | Fastest; never starts `MSACCESS.EXE`; enough for tables, relationships, queries and data |
+| Access-hosted DAO | Bitness differs, or `engine="access"` | A hidden Access instance that PyAccessKit owns hosts DAO; the database is **not** opened in the Access UI, so no startup code runs |
+| Design session | First use of forms, modules or text I/O | The database becomes Access's current database; handles such as `db.tables["X"]` keep working across the switch |
+
+| Python | Office | In-process DAO | Access transports |
+|---|---|---|---|
+| 64-bit | 64-bit | ✅ | ✅ |
+| 32-bit | 32-bit | ✅ | ✅ |
+| 64-bit | 32-bit (common with Microsoft 365) | ❌ | ✅ |
+| 32-bit | 64-bit | ❌ | ✅ |
+
+`pyaccesskit doctor` explains what applies to your machine.
+
+## Safety guarantees
+
+- **Never touches your own Access windows.** PyAccessKit always starts a *new* Access instance
+  (`CoCreateInstanceEx`, local server). It never attaches to a running Access (which `Dispatch()` does),
+  so it can never close your work.
+- **No orphaned `MSACCESS.EXE`.** Every Access process it starts is identified by PID, creation time and
+  image, and placed in a kill-on-close job object. If Python crashes, Windows ends the process. The process
+  is also recorded in an ownership ledger: `pyaccesskit cleanup` ends leftovers from crashed sessions, and
+  only when their Python owner is gone. Processes it did not start are never touched.
+- **Exceptions clean up too.** Closing runs every cleanup step even if one fails. Cleanup failures are
+  attached as notes to the exception that caused the close, never masking it.
+- **Atomic creation.** `AccessDatabase.create()` builds in a hidden sibling file and moves it into place
+  only on success. Tables are created all-or-nothing, and forms are built under a temporary name and
+  swapped in.
+- **No hangs on hidden dialogs.** A watchdog watches the windows of *our* Access process. Unexpected
+  dialogs are dismissed and reported as `AccessDialogError` with their text. Calls that exceed
+  `call_timeout` end the owned process, and Ctrl+C works during long calls.
+- **No startup code by default.** Databases are opened with macros disabled. Read-only sessions never open
+  the database in the Access UI, so `AutoExec` and startup forms do not run.
+
+## Errors you can act on
+
+COM errors are translated into specific exceptions. Each one carries what PyAccessKit was doing, the
+object involved, and the original Access or DAO error:
+
+```python
+from pyaccesskit import AccessDatabase, IntegrityViolationError
+
+with AccessDatabase.open("crm.accdb") as db:
+    try:
+        db.execute("INSERT INTO Orders (CustomerID, Total) VALUES (999, 10)")
+    except IntegrityViolationError as exc:
+        print(exc)  # what failed, with Access's own explanation
+        print(exc.details.number)  # 3201: there is no related record in Customers
+```
+
+Most mistakes are caught before Access is involved at all. A duplicate table name, an unknown column in a
+relationship, or incompatible key types each raise a precise `ObjectExistsError`, `SpecError` or
+`RelationshipError`.
+
+## Command line
+
+```console
+pyaccesskit doctor [--json] [--probe]      # environment report (exit code 3 if nothing works)
+pyaccesskit inspect DB [--json] [--counts] # tables, relationships, queries, objects; read-only
+pyaccesskit cleanup [--dry-run] [--json]   # end orphaned Access processes started by PyAccessKit
+pyaccesskit guide [--path]                 # the guide for AI coding agents
+pyaccesskit schema [KIND]                  # JSON Schema of the specs
+```
+
+Exit codes: `0` success, `1` error, `2` usage error, `3` environment unusable.
+
+## Documentation
+
+- [Getting started](https://ariedotcodotnz.github.io/PyAccessKit/getting-started/) and [recipes](https://ariedotcodotnz.github.io/PyAccessKit/guides/recipes/)
+- **[Building with AI agents](https://ariedotcodotnz.github.io/PyAccessKit/agents/)**: `pyaccesskit guide` prints a version-matched guide
+  that lets coding agents write Access applications with PyAccessKit; `pyaccesskit schema` prints the
+  JSON Schemas of the specs; the site publishes `llms.txt` and `llms-full.txt`.
+- Concepts: [engines](https://ariedotcodotnz.github.io/PyAccessKit/concepts/engines/), [lifecycle](https://ariedotcodotnz.github.io/PyAccessKit/concepts/lifecycle/),
+  [specs](https://ariedotcodotnz.github.io/PyAccessKit/concepts/specs/)
+- Guides: [tables](https://ariedotcodotnz.github.io/PyAccessKit/guides/tables/), [relationships](https://ariedotcodotnz.github.io/PyAccessKit/guides/relationships/),
+  [queries](https://ariedotcodotnz.github.io/PyAccessKit/guides/queries/), [forms](https://ariedotcodotnz.github.io/PyAccessKit/guides/forms/), [modules](https://ariedotcodotnz.github.io/PyAccessKit/guides/modules/),
+  [text I/O](https://ariedotcodotnz.github.io/PyAccessKit/guides/text-io/)
+- Reference: [errors](https://ariedotcodotnz.github.io/PyAccessKit/reference/errors/), [data types](https://ariedotcodotnz.github.io/PyAccessKit/reference/data-types/),
+  [command line](https://ariedotcodotnz.github.io/PyAccessKit/reference/cli/), and an API reference generated from the docstrings
+- [Environment & troubleshooting](https://ariedotcodotnz.github.io/PyAccessKit/environment/), [FAQ](https://ariedotcodotnz.github.io/PyAccessKit/faq/),
+  [contributing](https://ariedotcodotnz.github.io/PyAccessKit/contributing/), [architecture decisions](https://github.com/ariedotcodotnz/PyAccessKit/tree/HEAD/docs/adr)
+- Examples: [`examples/`](https://github.com/ariedotcodotnz/PyAccessKit/tree/HEAD/examples) (`04_inventory_app.py` is the complete, tested application the agent
+  guide walks through)
+
+## License
+
+MIT. See [LICENSE](https://github.com/ariedotcodotnz/PyAccessKit/blob/HEAD/LICENSE).

pyaccesskit-0.1.0/README.md

@@ -0,0 +1,170 @@
+# PyAccessKit
+
+A modern, typed, Pythonic toolkit for building and modifying Microsoft Access databases (`.accdb`) and,
+progressively, whole Access applications without raw `pywin32` calls, DAO magic numbers or orphaned
+`MSACCESS.EXE` processes.
+
+```python
+from pyaccesskit import AccessDatabase, Column, Expr, Vba, cm
+
+with AccessDatabase.create("crm.accdb") as db:
+    db.tables.create(
+        "Customers",
+        columns=[
+            Column.autonumber("CustomerID", primary_key=True),
+            Column.text("CustomerName", length=200, required=True),
+            Column.text("Email", length=255, unique=True),
+            Column.date_time("CreatedAt", default=Expr("Now()")),
+        ],
+    )
+    db.tables.create(
+        "Orders",
+        columns=[
+            Column.autonumber("OrderID", primary_key=True),
+            Column.number("CustomerID", required=True),  # Long Integer, as in Access
+            Column.currency("Total", default=0),
+        ],
+    )
+    db.relationships.create("Customers.CustomerID", "Orders.CustomerID", cascade_delete=True)
+    db.queries.create("qryCustomers", "SELECT * FROM Customers ORDER BY CustomerName;")
+
+    with db.forms.create("frmCustomers", record_source="Customers", caption="Customers") as form:
+        form.textbox("CustomerName", label="Customer name", width=cm(8))
+        form.textbox("Email")
+        form.button("cmdClose", caption="Close", on_click=Vba("DoCmd.Close acForm, Me.Name"))
+```
+
+When the `with` block ends, the database file appears at `crm.accdb`, and any Access process PyAccessKit
+started is closed. If the block raises, no file is created and nothing is left running.
+
+> **Status:** alpha (`0.1.0`). The API may still change between 0.x releases.
+
+## Installation
+
+```console
+pip install pyaccesskit
+```
+
+Requirements:
+
+- Windows 10 or 11 and CPython 3.11–3.14 (64- or 32-bit; free-threaded builds are not supported).
+- Microsoft Access 2016 or later, including Microsoft 365. Alternatively, the Microsoft 365 Access Runtime
+  with a Python of the same bitness, for schema and data work only.
+
+Check your machine with:
+
+```console
+pyaccesskit doctor          # which engines work here, and why not
+pyaccesskit doctor --probe  # also builds a scratch database end to end
+```
+
+The spec models (`TableSpec`, `Column`, `FormSpec`, units, layout…) are pure Python and also import on
+Linux and macOS, so you can validate specs in CI without Access.
+
+## What you can do in 0.1
+
+| Area | Highlights | Stability |
+|---|---|---|
+| Lifecycle | Atomic `create()`, `open()` (read-only/shared, exclusive, password), guaranteed cleanup, `db.raw` escape hatch | stable-track |
+| Tables | Every common column type, defaults as Python values or `Expr`, validation rules, captions, formats, input masks; indexes (composite, descending, unique, primary); add, drop and rename columns and indexes; `to_spec()` round-trips | stable-track |
+| Relationships | Single and composite keys, referential integrity, cascades, join types, all checked before Access sees them | stable-track |
+| Queries & data | Saved queries (select, action, union, crosstab, pass-through), parameters bound by name, `execute()` / `fetch_all()` | stable-track |
+| Forms | Labels, text boxes, check boxes, combo boxes and buttons; stacked or tabular layout; VBA event procedures; atomic build-then-swap replacement | provisional |
+| Modules & text I/O | Standard and class modules; `SaveAsText`/`LoadFromText` for forms, reports, macros, queries and modules, stored as UTF-8 | provisional |
+| Decimal columns | `Column.decimal(precision=…, scale=…)` via ADO DDL | provisional |
+
+Reports, linked tables, VBA references, and the declarative `build`/`plan`/`apply` workflow are planned
+(see the [roadmap](https://ariedotcodotnz.github.io/PyAccessKit/#roadmap)).
+
+## Engines
+
+PyAccessKit reaches the database in one of three ways and picks one for you (`engine="auto"`):
+
+| Engine | When | Notes |
+|---|---|---|
+| In-process DAO | Python and Office have the **same bitness** | Fastest; never starts `MSACCESS.EXE`; enough for tables, relationships, queries and data |
+| Access-hosted DAO | Bitness differs, or `engine="access"` | A hidden Access instance that PyAccessKit owns hosts DAO; the database is **not** opened in the Access UI, so no startup code runs |
+| Design session | First use of forms, modules or text I/O | The database becomes Access's current database; handles such as `db.tables["X"]` keep working across the switch |
+
+| Python | Office | In-process DAO | Access transports |
+|---|---|---|---|
+| 64-bit | 64-bit | ✅ | ✅ |
+| 32-bit | 32-bit | ✅ | ✅ |
+| 64-bit | 32-bit (common with Microsoft 365) | ❌ | ✅ |
+| 32-bit | 64-bit | ❌ | ✅ |
+
+`pyaccesskit doctor` explains what applies to your machine.
+
+## Safety guarantees
+
+- **Never touches your own Access windows.** PyAccessKit always starts a *new* Access instance
+  (`CoCreateInstanceEx`, local server). It never attaches to a running Access (which `Dispatch()` does),
+  so it can never close your work.
+- **No orphaned `MSACCESS.EXE`.** Every Access process it starts is identified by PID, creation time and
+  image, and placed in a kill-on-close job object. If Python crashes, Windows ends the process. The process
+  is also recorded in an ownership ledger: `pyaccesskit cleanup` ends leftovers from crashed sessions, and
+  only when their Python owner is gone. Processes it did not start are never touched.
+- **Exceptions clean up too.** Closing runs every cleanup step even if one fails. Cleanup failures are
+  attached as notes to the exception that caused the close, never masking it.
+- **Atomic creation.** `AccessDatabase.create()` builds in a hidden sibling file and moves it into place
+  only on success. Tables are created all-or-nothing, and forms are built under a temporary name and
+  swapped in.
+- **No hangs on hidden dialogs.** A watchdog watches the windows of *our* Access process. Unexpected
+  dialogs are dismissed and reported as `AccessDialogError` with their text. Calls that exceed
+  `call_timeout` end the owned process, and Ctrl+C works during long calls.
+- **No startup code by default.** Databases are opened with macros disabled. Read-only sessions never open
+  the database in the Access UI, so `AutoExec` and startup forms do not run.
+
+## Errors you can act on
+
+COM errors are translated into specific exceptions. Each one carries what PyAccessKit was doing, the
+object involved, and the original Access or DAO error:
+
+```python
+from pyaccesskit import AccessDatabase, IntegrityViolationError
+
+with AccessDatabase.open("crm.accdb") as db:
+    try:
+        db.execute("INSERT INTO Orders (CustomerID, Total) VALUES (999, 10)")
+    except IntegrityViolationError as exc:
+        print(exc)  # what failed, with Access's own explanation
+        print(exc.details.number)  # 3201: there is no related record in Customers
+```
+
+Most mistakes are caught before Access is involved at all. A duplicate table name, an unknown column in a
+relationship, or incompatible key types each raise a precise `ObjectExistsError`, `SpecError` or
+`RelationshipError`.
+
+## Command line
+
+```console
+pyaccesskit doctor [--json] [--probe]      # environment report (exit code 3 if nothing works)
+pyaccesskit inspect DB [--json] [--counts] # tables, relationships, queries, objects; read-only
+pyaccesskit cleanup [--dry-run] [--json]   # end orphaned Access processes started by PyAccessKit
+pyaccesskit guide [--path]                 # the guide for AI coding agents
+pyaccesskit schema [KIND]                  # JSON Schema of the specs
+```
+
+Exit codes: `0` success, `1` error, `2` usage error, `3` environment unusable.
+
+## Documentation
+
+- [Getting started](https://ariedotcodotnz.github.io/PyAccessKit/getting-started/) and [recipes](https://ariedotcodotnz.github.io/PyAccessKit/guides/recipes/)
+- **[Building with AI agents](https://ariedotcodotnz.github.io/PyAccessKit/agents/)**: `pyaccesskit guide` prints a version-matched guide
+  that lets coding agents write Access applications with PyAccessKit; `pyaccesskit schema` prints the
+  JSON Schemas of the specs; the site publishes `llms.txt` and `llms-full.txt`.
+- Concepts: [engines](https://ariedotcodotnz.github.io/PyAccessKit/concepts/engines/), [lifecycle](https://ariedotcodotnz.github.io/PyAccessKit/concepts/lifecycle/),
+  [specs](https://ariedotcodotnz.github.io/PyAccessKit/concepts/specs/)
+- Guides: [tables](https://ariedotcodotnz.github.io/PyAccessKit/guides/tables/), [relationships](https://ariedotcodotnz.github.io/PyAccessKit/guides/relationships/),
+  [queries](https://ariedotcodotnz.github.io/PyAccessKit/guides/queries/), [forms](https://ariedotcodotnz.github.io/PyAccessKit/guides/forms/), [modules](https://ariedotcodotnz.github.io/PyAccessKit/guides/modules/),
+  [text I/O](https://ariedotcodotnz.github.io/PyAccessKit/guides/text-io/)
+- Reference: [errors](https://ariedotcodotnz.github.io/PyAccessKit/reference/errors/), [data types](https://ariedotcodotnz.github.io/PyAccessKit/reference/data-types/),
+  [command line](https://ariedotcodotnz.github.io/PyAccessKit/reference/cli/), and an API reference generated from the docstrings
+- [Environment & troubleshooting](https://ariedotcodotnz.github.io/PyAccessKit/environment/), [FAQ](https://ariedotcodotnz.github.io/PyAccessKit/faq/),
+  [contributing](https://ariedotcodotnz.github.io/PyAccessKit/contributing/), [architecture decisions](https://github.com/ariedotcodotnz/PyAccessKit/tree/HEAD/docs/adr)
+- Examples: [`examples/`](https://github.com/ariedotcodotnz/PyAccessKit/tree/HEAD/examples) (`04_inventory_app.py` is the complete, tested application the agent
+  guide walks through)
+
+## License
+
+MIT. See [LICENSE](https://github.com/ariedotcodotnz/PyAccessKit/blob/HEAD/LICENSE).

pyaccesskit-0.1.0/docs/adr/0001-spike-findings.md

@@ -0,0 +1,126 @@
+# ADR 0001 — Phase-0 spike findings
+
+- **Status:** accepted
+- **Date:** 2026-09-26
+- **Environment:** Microsoft 365 Apps (Current Channel) Access 16.0.20326.20158 **32-bit** Click-to-Run,
+  Windows 11, pywin32 312; CPython 3.14 x64 (Access transports) and CPython 3.12 x86 (in-process DAO).
+- **Scripts:** `scripts/spikes/s01…s10*.py` (throwaway; reproducible).
+
+Each finding lists the decision it drives. "✅" = assumption from the plan confirmed; "⚠️" = reality
+differed and the design was adjusted.
+
+## S1 — process ownership
+
+- ✅ Every `CoCreateInstanceEx(CLSCTX_LOCAL_SERVER)` starts a **new** `MSACCESS.EXE` (~1.1 s).
+- ✅ `app.hWndAccessApp()` works on a hidden instance with no database and resolves (via
+  `GetWindowThreadProcessId`) to the right process; `QueryFullProcessImageNameW` confirms `MSACCESS.EXE`.
+- ✅ A DCOM-launched Access **can** be assigned to our job object; closing the job handle kills it.
+- ✅ Defaults: `Visible=False`, `UserControl=False`, `AutomationSecurity=2` (ByUI).
+- ✅ `Quit(acQuitSaveNone)` → process exit in ~2.5 s; holding a child COM reference did not block exit.
+- `SysCmd(724)` → `'32-bit'`, `SysCmd(720)` → full version string, `SysCmd(6)` → runtime flag. Used by
+  `doctor --probe`.
+
+## S2 — `AutomationSecurity` and startup code
+
+| Open path | Opens | AutoExec runs | Dialogs | Design ops |
+|---|---|---|---|---|
+| Access-hosted DAO (`app.DBEngine.OpenDatabase`) | ✅ | never | 0 | n/a |
+| `ByUI` (default) in an untrusted folder | ✅ | no (Trust Center dependent) | 0 | ✅ |
+| `ForceDisable` | ✅ | **no** | 0 | ✅ |
+| `Low` | ✅ | **yes** | 0 | ✅ |
+
+⚠️ The documentation's warning that ForceDisable "will not open any database" does not apply to modern
+Access. **Decision:** default `macro_security = "disable"` (ForceDisable): deterministic, independent of the
+user's Trust Center. Code execution (`Application.Run`, 0.2) requires an explicit opt-in.
+
+## S3 — DAO- vs Access-created databases
+
+`NewCurrentDatabase` writes 15 database properties that DAO `CreateDatabase` does not; opening a
+DAO-created file in Access only adds nav-pane properties. The user-visible ones include `UseMDIMode=0`
+(tabbed documents), `ShowDocumentTabs=True`, `Themed Form Controls=1`.
+**Decision:** the in-process DAO transport applies this **native defaults profile** (see
+`_backends/dao/profile.py`) so output is identical whichever engine created the file. `dbVersion120` is the
+creation format (`dbVersion150/167` still report `Version=12.0`).
+
+## S4 — Decimal(p, s)
+
+- ✅ DAO DDL rejects `DECIMAL` (3292); ADO DDL (`CurrentProject.Connection` or in-process ADODB + ACE
+  OLEDB) supports ADD/ALTER/CREATE with precision and scale.
+- ⚠️ DAO `CreateField(..., dbDecimal)` silently produces a **BigInt (Type 16)** field, even after setting
+  `Precision`/`Scale`. **Never create decimals through DAO.**
+- ✅ DAO *reads* precision/scale through the hidden `Field.Properties("Precision"/"Scale")` (only meaningful
+  when `Type == 20`) — introspection needs no ADO.
+- In-process ADO cannot open a file DAO holds exclusively → the in-process transport closes DAO, runs the
+  ADO DDL, and reopens (S10).
+
+## S5 — QueryDefs
+
+- ⚠️ Jet **rewrites** SQL: uppercases keywords, one clause per line, appends `;\r\n` (DDL/UNION are kept
+  closer to verbatim). **Decision:** store what Access stores; compare with a whitespace/case-insensitive
+  normalizer.
+- ✅ No reference validation at save time (missing tables and not-yet-created queries are accepted) →
+  `build` needs no topological ordering of queries.
+- ✅ Tables and queries share one namespace (3012 / 3010).
+- ⚠️ `QueryDef.Type` reads `0` until `QueryDefs.Refresh()`; afterwards append=64, crosstab=16, DDL=96,
+  delete=32, make-table=80, pass-through=112, union=128, update=48. **Always refresh before enumerating.**
+- Parameters come back **bracketed** (`[pMin]`); a bracketed identifier matching a column is a column, not
+  a parameter. Pass-through: `CreateQueryDef(name)` then `Connect` → `SQL` works with no reachable DSN.
+- `Recordset.GetRows(n)` returns column-major tuples.
+
+## S6 — forms in a hidden instance
+
+- ⚠️ pywin32 dynamic dispatch cannot call **indexed properties** (`Form.Section(0)` → "Member not found")
+  and raises `AttributeError` (not `com_error`) for members missing from a specific control's typeinfo
+  (e.g. `Label.ControlSource`). **Decision:** the COM gateway performs its own `IDispatch.Invoke` by DISPID
+  with the exact arguments for property reads, indexed properties, and method calls.
+- ✅ `CreateForm` → properties → `CreateControl` (+ attached labels via `Parent`) → `HasModule` +
+  `Module.AddFromString` → `DoCmd.Close(acSaveYes)` → `DoCmd.Rename` works; geometry round-trips exactly;
+  the form opens in Form view (hidden) and binds data.
+- ✅ Unsaved forms closed with `acSaveNo` leave nothing behind (free rollback).
+- ✅ Header/footer: `DoCmd.RunCommand(acCmdFormHdrFtr)` right after `CreateForm` works hidden;
+  `CreateControl` into a missing section raises 2148.
+- ✅ Build-then-swap with a hidden `~pak_bak_…` backup name works.
+- ⚠️ A modal **"Save As"** dialog appears in the *hidden* instance when `CloseCurrentDatabase` finds unsaved
+  new objects. **Decision:** close every open form/report with `acSaveNo` before closing the database, and
+  keep the dialog watchdog alive until the process has exited.
+
+## S7 — SaveAsText / LoadFromText
+
+- Forms, queries and macros export as **UTF-16LE with BOM**; they must be re-imported as UTF-16LE (UTF-8
+  without BOM loses non-ASCII text).
+- ⚠️ Modules are read **and** written in the **ANSI code page** (cp1252 here); UTF-8 is mangled and a UTF-8
+  BOM becomes literal `` code. **Decision:** module codec = ANSI; reject unrepresentable characters.
+- ⚠️ Class modules: Access exports them with four leading `Attribute VB_GlobalNameSpace/Creatable/
+  PredeclaredId/Exposed` lines (no `VERSION 1.0 CLASS` header); `LoadFromText` uses those lines to create a
+  class module. A VB6-style header yields an empty *standard* module. **Decision:** the codec adds/strips
+  exactly Access's header.
+- `LoadFromText` silently overwrites existing objects; imported objects persist.
+- VBE (`app.VBE.ActiveVBProject.VBComponents`) is accessible without Trust Center changes.
+
+## S8 — dialogs
+
+- ✅ pywin32 releases the GIL during `Invoke`; a watcher thread detects our PID's visible windows while the
+  call blocks. `WM_CLOSE` dismisses OK boxes; **Yes/No boxes ignore `WM_CLOSE`** and need `BM_CLICK` on a
+  button (preference Cancel → No → OK). Button captions carry mnemonics (`&No`).
+- ⚠️ `app.Run("Proc")` through pywin32's typed wrapper fails (`DISP_E_BADPARAMCOUNT`); an exact-argument
+  `Invoke` works (`'ok'`, `Add2(2,3) → 5`). Same root cause as S6.
+
+## S9 — errors
+
+- All Access/DAO errors arrive as `DISP_E_EXCEPTION` with `scode = 0x800A0000 | number`; DAO errors carry
+  `source='DAO.<Collection>'`, Access errors `source=None` with a filled description.
+- Verified numbers: 3265, 3010, 3012, 3191, 3270, 3609 (no unique index for relationship), 3201 (existing
+  data violates integrity), 3368, 3125, 3141, 3129, 3075, 3061, 3292, 2102, 2148, 2149, 2220, 2462, 2467,
+  2493, 3045, 3024, 3343, 3204, 7865, 7866, 7874.
+- ⚠️ `DBEngine.Errors` keeps **stale** entries after Access-level errors → attach it only when its last
+  entry matches the current error number.
+- ⚠️ **`OpenCurrentDatabase` fails silently** (no exception, no dialog) for locked or non-database files:
+  `CurrentProject.FullName == ''`, `CurrentDb() is None`. **Decision:** verify every open and, on failure,
+  probe with DAO `OpenDatabase` to raise the precise error (locked / format / missing).
+
+## S10 — in-process DAO (x86 Python, C2R Office)
+
+- ✅ `DAO.DBEngine.120` and ADODB + `Microsoft.ACE.OLEDB.16.0` work in-process from 32-bit Python under
+  Click-to-Run (engine ready in ~0.1 s).
+- ADO cannot open a file DAO holds exclusively; with DAO closed, ADO decimal DDL works and DAO then reads
+  `Precision`/`Scale` correctly.

pyaccesskit-0.1.0/docs/adr/0002-integration-findings.md

@@ -0,0 +1,24 @@
+# ADR 0002 — Findings from the first integration runs
+
+- **Status:** accepted
+- **Date:** 2026-09-26
+- **Context:** the first end-to-end runs of the full stack (smoke script, contract suite on real Access,
+  lifecycle and round-trip suites) surfaced behaviours the Phase-0 spikes had not exercised. Each one is now
+  covered by a test.
+
+| # | Finding | Decision |
+|---|---|---|
+| 1 | ``DoCmd.SetWarnings`` raises Access error 2046 ("isn't available now") when no database is open. | Called (best effort) only after a design session has a current database. |
+| 2 | Late-bound ``Index.Fields`` of an *appended* index returns a **string** (``"+Col1;-Col2"``), not a collection. | ``_index_fields`` parses the string form (``+`` ascending, ``-`` descending). |
+| 3 | pywin32's dynamic dispatch resolves ``Item`` as a *property* on some DAO collections and returns the wrong object. | All DAO collection access goes through the gateway's exact ``IDispatch.Invoke`` (``_item``). |
+| 4 | pywin32 treats a naive ``datetime`` as local time and converts it to UTC when building a ``VT_DATE`` (a 13-hour shift was observed). | ``to_variant`` passes wall-clock values as UTC-tagged datetimes; ``normalize`` reads the wall-clock back. |
+| 5 | DAO silently ignores ``DefaultValue`` on an auto-increment field, so *random* AutoNumbers (``GenUniqueID()``) cannot be created. | ``AutoNumberColumn(new_values=...)`` was removed rather than shipped half-working. |
+| 6 | Releasing a COM proxy after Access has exited makes COM raise-and-handle ``RPC_E_DISCONNECTED``; ``faulthandler`` prints it as a "Windows fatal exception". | ``gc.collect()`` before quitting releases unreachable proxies while Access is alive; the test-suite disables pytest's faulthandler plugin. |
+| 7 | ``WaitForSingleObject`` needs ``SYNCHRONIZE``; a query-only handle made live orphans look "already exited". | Identity checks open processes with ``SYNCHRONIZE | PROCESS_QUERY_LIMITED_INFORMATION``. |
+| 8 | Race: dismissing a dialog unblocks the COM call before the watchdog had recorded the dialog. | Dialogs are recorded *before* dismissal; ``end()`` waits for in-progress handling. |
+| 9 | After the watchdog terminated Access (timeout), shutdown's COM steps could only fail. | Shutdown skips COM steps when the owned process is already gone; closing stays quiet. |
+| 10 | ``AutomationSecurity`` (``macro_security``) disables VBA and ``AutoExec``, but ``OpenCurrentDatabase`` still opens the database's ``StartUpForm``; with code disabled the form can raise a dialog, so design sessions failed on apps that set one. | Before a design open the engine removes ``StartUpForm`` through DAO (which runs nothing) and restores it as soon as the database is open (or through DAO again if the open fails). |
+| 11 | Access-application functions (``Nz``, VBA functions from modules) are unavailable to SQL run through DAO outside the Access UI (DAO error 3085 "Undefined function"). They do work in form control sources. | Documented for users and agents: SQL that Python runs uses engine functions only (``IIf``, ``IsNull``…). |
+| 12 | A VBA module that does not compile is only reported when Access next compiles code, e.g. when a form expression uses it (Access error 7960 during the form build). | Documented; ``check_opens()`` on every form is the recommended verification step. A dedicated ``VbaCompileError`` is planned for 0.2. |
+| 13 | Implicit QueryDef parameters (a bare ``[name]`` in SQL) are typed as text; binding ``bytes`` to one stores a corrupted, doubled value. ``Parameter.Type`` cannot be changed for implicit parameters. | Ad-hoc SQL declares bytes-valued parameters (``PARAMETERS [x] LongBinary;``) automatically; saved queries with a non-binary parameter reject bytes with ``SpecError`` explaining the declaration. OLE/binary values read back as ``bytes``. |
+| 14 | A database created by in-process DAO has no ``Forms``/``Reports``/``Scripts``/``Modules`` containers until Access opens it; reading ``Containers("Forms")`` fails with error 3265. | Listing objects of a kind whose container is missing returns an empty list. |

pyaccesskit-0.1.0/docs/agents/guide.md

@@ -0,0 +1,3 @@
+<!-- The agent guide ships inside the package (pyaccesskit guide); this page includes that file. -->
+
+--8<-- "src/pyaccesskit/AGENT_GUIDE.md"