diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index e3a6580..9b6287b 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,5 +1,5 @@ blank_issues_enabled: true contact_links: - name: Security reports - url: https://github.com/CivicSuite/civiczone/security/policy + url: https://github.com/Townlight/townlight_zoning/security/policy about: Report vulnerabilities privately. diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 982e8cb..681f401 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -20,8 +20,10 @@ jobs: python-version: "3.11" cache: pip - - name: Install CivicCore release wheel - run: python -m pip install https://github.com/CivicSuite/civiccore/releases/download/v1.1.0/civiccore-1.1.0-py3-none-any.whl + - name: Build and install exact candidate Core + run: | + python -m pip install build + python scripts/install-core-candidate.py - name: Install package and test dependencies run: python -m pip install -e ".[dev]" @@ -32,11 +34,11 @@ jobs: - name: Create release notes run: | cat > release-notes.md <> "$GITHUB_ENV" - echo "CIVICZONE_TEST_DATABASE_URL=$URL" >> "$GITHUB_ENV" + echo "TOWNLIGHT_ZONING_TEST_DATABASE_URL=$URL" >> "$GITHUB_ENV" - name: Apply database migrations - run: DATABASE_URL="$CIVICZONE_TEST_DATABASE_URL" alembic -c civiczone/migrations/alembic.ini upgrade head + run: DATABASE_URL="$TOWNLIGHT_ZONING_TEST_DATABASE_URL" alembic -c townlight_zoning/migrations/alembic.ini upgrade head - name: Run release gate run: bash scripts/verify-release.sh - name: Remove PostGIS test database if: always() - run: docker rm -f civiczone-ci || true + run: docker rm -f townlight_zoning-ci || true diff --git a/AGENTS.md b/AGENTS.md index 777198a..6160980 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,12 +1,33 @@ - + # Townlight Zoning Agent Contract +## Governing contract and candidate identity + +Scott's bounded completion contract governs. Legacy skills, automatic delegation, +milestone/review loops and generic extra gates require explicit invocation. +Preserve actual product requirements, required CI/release checks, security/data +safeguards and installed acceptance. Reuse unaffected evidence with its limits. + +Current distribution: `townlight-zoning` 0.2.3; principal import: +`townlight_zoning`. Shared dependency: `townlight-core==1.3.0.dev2`. Use the exact +coordinated source pins and local candidate wheels in the README; never fabricate +renamed historical release URLs. Source tests do not establish installed acceptance +or publication. The original [agent contract](docs/history/pre-naming-2026-11/AGENTS.md) +is retained as history, not current session authorization. + +The candidate supports fresh branded databases and fresh profiles only. Preserve +existing data and refuse unmarked legacy initialization; no in-place upgrade or +old import shim is provided. The sole approved old active identifier is +`%LOCALAPPDATA%\CivicSuite` for that profile path only. Other retained old active +identifiers require Scott's approval in the single exception registry. Preserve +historical identities, third-party attribution and standalone CivicCast. + ## Source Of Truth -- Upstream suite spec: `townlight/townlight/docs/CivicSuiteUnifiedSpec.md`, especially section 10. +- Upstream suite spec: `townlight/townlight/docs/TownlightUnifiedSpec.md`, especially section 10. - Suite ADRs: `townlight/townlight/docs/architecture/`. -- Townlight Code v0.1.0 release contract is required context for zoning-code citations. +- The pinned Townlight Code candidate contract and source provenance govern zoning-code citations. ## Non-Negotiables @@ -18,10 +39,17 @@ - Townlight Zoning depends on Townlight Core and Townlight Code; Townlight Core must never depend on Townlight Zoning. - Code is AGPL-3.0-only, with no additional permission for this candidate (historical grants under docs/licensing/history/). Docs are CC BY 4.0. -## Placeholder Package Warning +## Core dependency boundary -Do not import from Townlight Core placeholder packages until Townlight Core ships real implementations for them: `audit`, `catalog`, `connectors`, `exemptions`, `ingest`, `notifications`, `onboarding`, `scaffold`, `search`, `verification`. Townlight Core `auth` is no longer treated as a placeholder for Townlight Zoning v1.0.0 because the current release uses its trusted-header helpers for staff access validation. +Core auth, audit, catalog, connector, ingestion, exemption, search, scaffold and +verification contracts must be assessed against the pinned implementation. +Historical placeholder ADRs do not establish current absence. Keep the owning +product's dependency-boundary checks; this correction does not add consumers or +authorize importing an unused capability. -## Milestone Rule +## Verification -Work one milestone at a time. When a milestone is done, report what changed, audit it once, fix findings once, re-audit once, then continue immediately unless there is a true blocker. +Run meaningful affected checks and the repository-required release checks. +Report database, Docker and installed-workflow evidence separately; never turn +skips or historical results into current acceptance. Follow the bounded contract +for completion and continuation rather than an automatic audit/re-audit loop. diff --git a/CHANGELOG.md b/CHANGELOG.md index 4881466..fe1136b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## [0.2.3] - Unreleased naming candidate + +- Rename the principal distribution/import to the Townlight Zoning identities and pair with Townlight Core 1.3.0.dev2. +- Update renamed cross-product consumers and fresh-install schema identities. +- Fresh-install candidate only; no legacy database upgrade or import shim. Existing data and historical release identities are preserved. +- Signed Windows installer acceptance and publication remain pending; source implementation is not installed verification. + + ## Unreleased — Townlight Zoning Z3 - Persist explicit permitted Meetings source links as append-only question events. diff --git a/README.md b/README.md index faecdcd..0f94176 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ -> **Townlight Beta 1 release:** [signed Windows installer, exact owned source, documentation and acceptance](https://github.com/townlight/townlight/releases/tag/townlight-beta-1). [Online manual](https://townlight.github.io/manuals/zoning.html). This retained manual edition describes the accepted candidate before publication; distribution has changed, component versions and signed bytes have not. +> **Prepared naming, Access and Notice candidate — 2 November 2026.** Build, signing, installed acceptance and publication remain pending. Earlier signed releases and receipts apply only to their identified artifacts. # Townlight Zoning -**Townlight Beta 1** · Existing component versions retained · AGPL-3.0-only +**Townlight Beta 1** · Naming candidate; component versions advanced · AGPL-3.0-only Zoning combines local parcel geometry, cited zoning rules and staff review. It retains questions, corrections and snapshots with provenance so downstream staff can identify the precise evidence used. ## Start here -Staff should use the operating manual. Administrators should read first-run, configuration and recovery before changing a deployment. Developers should read the exact API/schema reference and matching source companion. This edition accompanies Townlight Beta 1; use the release link above for the signed candidate and exact source/documentation archives. +Staff should use the operating manual. Administrators should read first-run, configuration and recovery before changing a deployment. Developers should read the exact API/schema reference and matching source companion. This edition describes the prepared source candidate; obtain its installer only after signing and installed acceptance identify the exact artifact. - [Operating manual](docs/beta-1/manuals/zoning.html) · [Printable PDF](docs/beta-1/pdf/Townlight-Zoning-Manual-Beta-1.pdf) · [Editable Word manual](docs/beta-1/docx/Townlight-Zoning-Manual-Beta-1.docx) - [API and data dictionary](docs/beta-1/api/zoning.html) · [OpenAPI JSON](docs/beta-1/api/zoning-openapi.json) @@ -18,17 +18,15 @@ Staff should use the operating manual. Administrators should read first-run, con | Identity | Value | | --- | --- | -| Public documentation identity | Townlight Beta 1 | -| Installer version | 1.6.0.1 | -| Product component | civiczone 0.2.2 | -| Native desktop source version | 1.6.0-1 | -| Candidate MSI SHA256 | `98bcdef11ebdf5c767f620c904ff49f85115fde3b5c23f62703b111e645aaf86` | -| Corresponding-source SHA256 | `84a23e1297e42d17b16cfc9e51b2dd78bc46414c0de8ad7ebd2466c1a409d06b` | -| Current owned software license | AGPL-3.0-only | -| Supported acceptance profile | Windows x64 fresh install; inspections-preview; separate Station configuration | +| Documentation | Townlight Beta 1 naming, Access and Notice candidate | +| Intended installer version | 1.7.0.1; build and acceptance pending | +| Native desktop source version | 1.7.0-1 | +| Product component | townlight-zoning 0.2.3 | +| Principal import package | townlight_zoning | +| Candidate hashes | Pending build, signing and installed acceptance | +| License | AGPL-3.0-only | - -“Townlight Beta 1” identifies this coordinated beta delivery. It does not renumber the installer, native binary, Python packages or historical receipts. Component versions may differ. This documentation is a later companion to unchanged signed bytes, not a rebuilt installer. Historical release pages and manuals describe their own versions and are not the download instructions for this private candidate. +Use a fresh profile and empty database. Existing unmarked city data is refused before initialization; no in-place upgrade is supported. Preserve the existing `%LOCALAPPDATA%\CivicSuite` profile, data and recovery material. Historical releases retain their original identities. ## What staff can do @@ -53,7 +51,7 @@ The operating manual now includes these existing procedures, with synthetic inpu ### Runtime and storage -The accepted package targets **Windows x64 fresh installation**. Its native shell uses **Rust 2021, Tauri 2 and Microsoft WebView2**; browser assets are JavaScript built with **Vite 8.1.6**. This describes the native desktop frontend; Station has a separate React operator, specified below or in its product manual. Canonical business workflows use bundled **CPython 3.13.5, FastAPI, Pydantic, SQLAlchemy and Alembic**, with **PostgreSQL 17 / PostGIS** and managed original files. The installed runtime tested here contains FastAPI 0.162.0. Package minimum Python requirements can differ from the bundled executable; the metadata reference preserves both. No stack rewrite is implied by the beta label. +This prepared source candidate targets **Windows x64 fresh installation**. Its native shell uses **Rust 2021, Tauri 2 and Microsoft WebView2**; browser assets are JavaScript built with **Vite 8.1.6**. This describes the native desktop frontend; Station has a separate React operator, specified below or in its product manual. Canonical business workflows use bundled **CPython 3.13.5, FastAPI, Pydantic, SQLAlchemy and Alembic**, with **PostgreSQL 17 / PostGIS** and managed original files. The prior accepted runtime contained FastAPI 0.162.0; this changed candidate requires its own installed dependency verification. Package minimum Python requirements can differ from the bundled executable; the metadata reference preserves both. No stack rewrite is implied by the beta label. The native transport is fixed to loopback `127.0.0.1:15480`; PostgreSQL uses the configured local runtime port (default `15432`). Optional local model service defaults to `127.0.0.1:15434`. Those are deployment defaults, not internet endpoints. The runtime has health, module and readiness endpoints; readiness is stronger than process existence. The task queue is the existing local Core task infrastructure, not an assertion that a separate Redis service is required for this desktop composition. @@ -67,7 +65,7 @@ Versioned saves use expected prior revision identifiers where defined. Reopen an ### Capacity and platform statements -This beta has synthetic single-profile workflow evidence. It does not have a published benchmark for concurrent staff capacity, minimum RAM/CPU, large-source limits or a field SLA. Do not turn a developer machine’s specification into a supported minimum. Installer size is 2,092,122,112 bytes before installation; allow additional disk for extracted runtime, database, originals, exports, media and backups. Select equipment/storage after sizing those actual workloads. +This beta has synthetic single-profile workflow evidence. It does not have a published benchmark for concurrent staff capacity, minimum RAM/CPU, large-source limits or a field SLA. Do not turn a developer machine’s specification into a supported minimum. The new installer size remains pending its build; allow additional disk for extracted runtime, database, originals, exports, media and backups. Select equipment/storage after sizing those actual workloads. The exact [runtime payload lock](docs/beta-1/reference/runtime-payload-lock.json) records pinned files, sizes and hashes. The [component metadata](docs/beta-1/reference/component-metadata.json) records shipped dependency declarations. These references are more precise than a manually copied dependency list. Third-party and historical license notices must accompany their matching payloads. @@ -83,8 +81,8 @@ The exact [runtime payload lock](docs/beta-1/reference/runtime-payload-lock.json ## Setup and operation 1. Obtain the identified signed private candidate and its corresponding-source companion from the beta coordinator. The landing pages in this documentation are not an installer download service. -2. On the intended fresh Windows test installation, verify the MSI hash and publisher signature before installing. Preserve unrelated profiles and recovery material. This candidate has fresh-install acceptance; historical in-place upgrades are unverified. -3. Launch Townlight under the intended named Windows account. Choose the storage folders. Select **Townlight Inspections candidate** (`inspections-preview`) for all eight desktop products. A narrower default selection will not expose all workspaces. +2. On the intended fresh Windows test installation, verify the MSI hash and publisher signature before installing. Preserve unrelated profiles and recovery material. Installed acceptance for this source candidate remains pending; no in-place legacy upgrade is supported. +3. Launch Townlight under the intended named Windows account. Choose the storage folders. Select **Townlight Inspections candidate** (`inspections-preview`) for the bounded desktop composition, including Access and Notice. A narrower default selection will not expose all workspaces. 4. Enter the city profile, time zone and contacts. Create the first named local administrator, sign in and choose protected backup storage. **Continue without local AI** is valid for the deterministic workflows. 5. Run Health Check and wait for readiness. Open Townlight. In System Health select **Finish Records Migration** to activate the canonical Python/PostgreSQL runtime. Do not fabricate migration receipts or seed accounts. 6. Create named staff through Settings. Import authorized sources using each product’s source library. All examples in this package are synthetic; they are not municipal authority. @@ -93,9 +91,9 @@ The exact [runtime payload lock](docs/beta-1/reference/runtime-payload-lock.json ## Configuration ### Native deployment configuration -Use Setup, Settings and System Health for supported staff operation. Administrators provision folders, backup storage, named accounts and the city profile. Select `inspections-preview` for the full eight-workspace desktop. Station remains a separate service boundary. Do not use a standalone product’s demo server as a substitute for the installed workspace. +Use Setup, Settings and System Health for supported staff operation. Administrators provision folders, backup storage, named accounts and the city profile. Select `inspections-preview` for the bounded desktop composition, including Access and Notice. Station remains a separate service boundary. Do not use a standalone product’s demo server as a substitute for the installed workspace. -Technical deployments use `TOWNLIGHT_PRODUCT_PROFILE`, `TOWNLIGHT_PROFILE_ROOT`, `DATABASE_URL`, `CIVICSUITE_RUNTIME_PORT`, `PORTAL_MODE` and the runtime-managed secret files. Treat database URLs and native session proofs as secrets. The installed native domain runtime explicitly refuses non-loopback binding. `PORTAL_MODE=private` is the accepted posture; changing it does not by itself commission an internet portal, authentication provider or reverse proxy. +Technical deployments use `TOWNLIGHT_PRODUCT_PROFILE`, `TOWNLIGHT_PROFILE_ROOT`, `DATABASE_URL`, `TOWNLIGHT_RUNTIME_PORT`, `PORTAL_MODE` and the runtime-managed secret files. Treat database URLs and native session proofs as secrets. The installed native domain runtime explicitly refuses non-loopback binding. `PORTAL_MODE=private` is the accepted posture; changing it does not by itself commission an internet portal, authentication provider or reverse proxy. The isolated documentation exporter sets a fictional profile and unusable synthetic database origin only to read schemas; those values are not deployment configuration. Keep deployment values in the intended process/account scope. An already-running process does not automatically inherit later environment edits. @@ -188,10 +186,10 @@ Use the corresponding source for the candidate rather than assuming the public d Relevant source contracts: -- `civiczone/geo_import.py` -- `civiczone/discretionary.py` -- `civicsuite_runtime/zoning_bridge.py` -- `civicsuite_runtime/zoning_records.py` +- `townlight_zoning/geo_import.py` +- `townlight_zoning/discretionary.py` +- `townlight_runtime/zoning_bridge.py` +- `townlight_runtime/zoning_records.py` The desktop package defines `npm run build`, `npm test`, `npm run test:browser` and its Tauri command. Python products retain their own `pyproject.toml`, tests and migrations; use the matching checkout’s declared dependencies and test configuration. Do not run a sample server against a production profile. This documentation build validates documentation only and reuses the separately identified installed acceptance; it does not claim a new complete application CI run. @@ -205,6 +203,30 @@ Keep Station’s dedicated database and media evidence together in its own backu On failure, record the time, selected composition, component/installer versions and exact message. Check System Health for stopped, starting, ready or failed dependencies. Use the existing Retry control after readiness; do not create duplicate business records to refresh a stale view. Share only a redacted diagnostic bundle. Preserve secrets, original evidence, recovery material and unrelated installations. +## Prepared package installation + +The renamed distributions are not yet published on a package index. Use the +matching verified candidate wheel directory, not a renamed historical release +URL. Installation of these Python packages is a developer/package check; +the signed Windows MSI and its installed acceptance remain separate. + +In a new Windows virtual environment, replace the example wheel-directory path +with the directory accompanying this candidate and verify its SHA256 manifest: + +```powershell +python -m venv .venv +.\.venv\Scripts\Activate.ps1 +$candidateWheels = (Resolve-Path 'C:\path\to\candidate-wheels').Path +python -m pip install (Join-Path $candidateWheels 'townlight_core-1.3.0.dev2-py3-none-any.whl') +python -m pip install (Join-Path $candidateWheels 'townlight_zoning-0.2.3-py3-none-any.whl') +python -c "import townlight_zoning; from importlib.metadata import version; print(version('townlight-zoning'))" +``` + +Expected principal import: `townlight_zoning`; expected distribution version: +`0.2.3`. Use a fresh empty database/profile for workflow testing. Existing +city data and the previous release remain untouched; no in-place upgrade or +old-import compatibility shim is supplied. + ## License and responsible use Current owned code is AGPL-3.0-only. Preserve full license, matching corresponding source, dependency notices and historical grants. Terms of use do not remove license rights. Source imports do not confer permission to publish third-party material. Review all automatic drafts and use the separate owning-product decision before official action. CivicCast remains independent. diff --git a/README.txt b/README.txt index faecdcd..2961a6c 100644 --- a/README.txt +++ b/README.txt @@ -1,214 +1,226 @@ -> **Townlight Beta 1 release:** [signed Windows installer, exact owned source, documentation and acceptance](https://github.com/townlight/townlight/releases/tag/townlight-beta-1). [Online manual](https://townlight.github.io/manuals/zoning.html). This retained manual edition describes the accepted candidate before publication; distribution has changed, component versions and signed bytes have not. + Prepared naming, Access and Notice candidate — 2 November 2026. Build, signing, installed acceptance and publication remain pending. Earlier signed releases and receipts apply only to their identified artifacts. -# Townlight Zoning +Townlight Zoning -**Townlight Beta 1** · Existing component versions retained · AGPL-3.0-only +Townlight Beta 1 · Naming candidate; component versions advanced · AGPL-3.0-only Zoning combines local parcel geometry, cited zoning rules and staff review. It retains questions, corrections and snapshots with provenance so downstream staff can identify the precise evidence used. -## Start here +Start here -Staff should use the operating manual. Administrators should read first-run, configuration and recovery before changing a deployment. Developers should read the exact API/schema reference and matching source companion. This edition accompanies Townlight Beta 1; use the release link above for the signed candidate and exact source/documentation archives. +Staff should use the operating manual. Administrators should read first-run, configuration and recovery before changing a deployment. Developers should read the exact API/schema reference and matching source companion. This edition describes the prepared source candidate; obtain its installer only after signing and installed acceptance identify the exact artifact. -- [Operating manual](docs/beta-1/manuals/zoning.html) · [Printable PDF](docs/beta-1/pdf/Townlight-Zoning-Manual-Beta-1.pdf) · [Editable Word manual](docs/beta-1/docx/Townlight-Zoning-Manual-Beta-1.docx) -- [API and data dictionary](docs/beta-1/api/zoning.html) · [OpenAPI JSON](docs/beta-1/api/zoning-openapi.json) -- [Product and suite directory](docs/beta-1/index.html) · [Terms and full license](docs/beta-1/terms.html) +- Operating manual · Printable PDF · Editable Word manual +- API and data dictionary · OpenAPI JSON +- Product and suite directory · Terms and full license -## Exact version and candidate +Exact version and candidate -| Identity | Value | -| --- | --- | -| Public documentation identity | Townlight Beta 1 | -| Installer version | 1.6.0.1 | -| Product component | civiczone 0.2.2 | -| Native desktop source version | 1.6.0-1 | -| Candidate MSI SHA256 | `98bcdef11ebdf5c767f620c904ff49f85115fde3b5c23f62703b111e645aaf86` | -| Corresponding-source SHA256 | `84a23e1297e42d17b16cfc9e51b2dd78bc46414c0de8ad7ebd2466c1a409d06b` | -| Current owned software license | AGPL-3.0-only | -| Supported acceptance profile | Windows x64 fresh install; inspections-preview; separate Station configuration | + Identity Value + ------------------------------- ------------------------------------------------------ + Documentation Townlight Beta 1 naming, Access and Notice candidate + Intended installer version 1.7.0.1; build and acceptance pending + Native desktop source version 1.7.0-1 + Product component townlight-zoning 0.2.3 + Principal import package townlight_zoning + Candidate hashes Pending build, signing and installed acceptance + License AGPL-3.0-only +Use a fresh profile and empty database. Existing unmarked city data is refused before initialization; no in-place upgrade is supported. Preserve the existing %LOCALAPPDATA%\CivicSuite profile, data and recovery material. Historical releases retain their original identities. -“Townlight Beta 1” identifies this coordinated beta delivery. It does not renumber the installer, native binary, Python packages or historical receipts. Component versions may differ. This documentation is a later companion to unchanged signed bytes, not a rebuilt installer. Historical release pages and manuals describe their own versions and are not the download instructions for this private candidate. +What staff can do -## What staff can do +- Prepare parcel data: Use the complete supported bundle, including jurisdiction, dataset metadata and original hashes. The coordinates must be EPSG:4326. A loose geometry file is not the full source envelope. +- Import and inspect: Check the complete source envelope before selecting Import parcel dataset. That control submits directly; inspect the saved validation/provenance result afterward. Correct a refused source bundle and preserve the evidence. Do not force acceptance by editing SQL. +- Register cited rules: Associate the zone, rule kind/key and value with the relevant public Code section. Inspect overlays and effective context. Leave missing authority visible for planner review. +- Ask a parcel question: Look up the intended parcel and ask the supported question. Read the returned citation, applicability and disclaimer. Do not present an uncertain answer as an official decision. +- Record review and context: Record a correction and its reason when needed. Select permitted Meetings history explicitly. Preserve the question/review history and distinguish staff-only precedent from public material. +- Create a snapshot: Review the audience and exact content before creating the immutable snapshot. A public snapshot must satisfy its permitted-source contract; choosing a public label does not sanitize private notes. +- Use it downstream: Select the exact snapshot for Records or the permitted provider path. The receiving workflow rechecks visibility, source identity and hash before retaining or exporting it. -- **Prepare parcel data:** Use the complete supported bundle, including jurisdiction, dataset metadata and original hashes. The coordinates must be EPSG:4326. A loose geometry file is not the full source envelope. -- **Import and inspect:** Check the complete source envelope before selecting Import parcel dataset. That control submits directly; inspect the saved validation/provenance result afterward. Correct a refused source bundle and preserve the evidence. Do not force acceptance by editing SQL. -- **Register cited rules:** Associate the zone, rule kind/key and value with the relevant public Code section. Inspect overlays and effective context. Leave missing authority visible for planner review. -- **Ask a parcel question:** Look up the intended parcel and ask the supported question. Read the returned citation, applicability and disclaimer. Do not present an uncertain answer as an official decision. -- **Record review and context:** Record a correction and its reason when needed. Select permitted Meetings history explicitly. Preserve the question/review history and distinguish staff-only precedent from public material. -- **Create a snapshot:** Review the audience and exact content before creating the immutable snapshot. A public snapshot must satisfy its permitted-source contract; choosing a public label does not sanitize private notes. -- **Use it downstream:** Select the exact snapshot for Records or the permitted provider path. The receiving workflow rechecks visibility, source identity and hash before retaining or exporting it. - -## Operating procedures and examples +Operating procedures and examples The operating manual now includes these existing procedures, with synthetic inputs, readback and limits. Follow the actual app boundary identified there; a standalone source capability is not automatically a desktop screen. -- [Discretionary processes and staff review](docs/beta-1/manuals/zoning.html#discretionary-processes-and-staff-review). -- [Explain the cited process](docs/beta-1/manuals/zoning.html#explain-the-cited-process). -- [Keep parcel import and inspection in the right order](docs/beta-1/manuals/zoning.html#keep-parcel-import-and-inspection-in-the-right-order). -- [Use the existing specialist review contracts](docs/beta-1/manuals/zoning.html#use-the-existing-specialist-review-contracts). +- Discretionary processes and staff review. +- Explain the cited process. +- Keep parcel import and inspection in the right order. +- Use the existing specialist review contracts. -## Architecture and data +Architecture and data -### Runtime and storage +Runtime and storage -The accepted package targets **Windows x64 fresh installation**. Its native shell uses **Rust 2021, Tauri 2 and Microsoft WebView2**; browser assets are JavaScript built with **Vite 8.1.6**. This describes the native desktop frontend; Station has a separate React operator, specified below or in its product manual. Canonical business workflows use bundled **CPython 3.13.5, FastAPI, Pydantic, SQLAlchemy and Alembic**, with **PostgreSQL 17 / PostGIS** and managed original files. The installed runtime tested here contains FastAPI 0.162.0. Package minimum Python requirements can differ from the bundled executable; the metadata reference preserves both. No stack rewrite is implied by the beta label. +This prepared source candidate targets Windows x64 fresh installation. Its native shell uses Rust 2021, Tauri 2 and Microsoft WebView2; browser assets are JavaScript built with Vite 8.1.6. This describes the native desktop frontend; Station has a separate React operator, specified below or in its product manual. Canonical business workflows use bundled CPython 3.13.5, FastAPI, Pydantic, SQLAlchemy and Alembic, with PostgreSQL 17 / PostGIS and managed original files. The prior accepted runtime contained FastAPI 0.162.0; this changed candidate requires its own installed dependency verification. Package minimum Python requirements can differ from the bundled executable; the metadata reference preserves both. No stack rewrite is implied by the beta label. -The native transport is fixed to loopback `127.0.0.1:15480`; PostgreSQL uses the configured local runtime port (default `15432`). Optional local model service defaults to `127.0.0.1:15434`. Those are deployment defaults, not internet endpoints. The runtime has health, module and readiness endpoints; readiness is stronger than process existence. The task queue is the existing local Core task infrastructure, not an assertion that a separate Redis service is required for this desktop composition. +The native transport is fixed to loopback 127.0.0.1:15480; PostgreSQL uses the configured local runtime port (default 15432). Optional local model service defaults to 127.0.0.1:15434. Those are deployment defaults, not internet endpoints. The runtime has health, module and readiness endpoints; readiness is stronger than process existence. The task queue is the existing local Core task infrastructure, not an assertion that a separate Redis service is required for this desktop composition. -The default native profile is `%LOCALAPPDATA%\CivicSuite`; the historical directory name remains part of compatibility. Do not rename it to Townlight. A configured `TOWNLIGHT_PROFILE_ROOT` must be absolute. Local configuration and secrets live under that profile; protected managed files and database state must be backed up coherently. Source/runtime identity is distinct from a product’s display label. +The default native profile is %LOCALAPPDATA%\CivicSuite; the historical directory name remains part of compatibility. Do not rename it to Townlight. A configured TOWNLIGHT_PROFILE_ROOT must be absolute. Local configuration and secrets live under that profile; protected managed files and database state must be backed up coherently. Source/runtime identity is distinct from a product’s display label. -### Data and consistency +Data and consistency GeoJSON import datasets; parcels and zone/overlay context; cited rules; questions and answers; review events; selected Meetings history; immutable snapshots. Versioned saves use expected prior revision identifiers where defined. Reopen and reconcile on conflict. Exact exports and handoffs use source IDs, current visibility, revision and SHA256. Review belongs to the saved revision and does not transfer silently to edited text. Database changes use the owning product’s migrations; a request or readiness check is not an authorization to mutate schema. -### Capacity and platform statements +Capacity and platform statements + +This beta has synthetic single-profile workflow evidence. It does not have a published benchmark for concurrent staff capacity, minimum RAM/CPU, large-source limits or a field SLA. Do not turn a developer machine’s specification into a supported minimum. The new installer size remains pending its build; allow additional disk for extracted runtime, database, originals, exports, media and backups. Select equipment/storage after sizing those actual workloads. + +The exact runtime payload lock records pinned files, sizes and hashes. The component metadata records shipped dependency declarations. These references are more precise than a manually copied dependency list. Third-party and historical license notices must accompany their matching payloads. -This beta has synthetic single-profile workflow evidence. It does not have a published benchmark for concurrent staff capacity, minimum RAM/CPU, large-source limits or a field SLA. Do not turn a developer machine’s specification into a supported minimum. Installer size is 2,092,122,112 bytes before installation; allow additional disk for extracted runtime, database, originals, exports, media and backups. Select equipment/storage after sizing those actual workloads. + --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + Data contract Description + ----------------------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------- + Input A supported EPSG:4326 GeoJSON envelope, jurisdiction and dataset metadata, public Code authority and permitted meeting evidence. -The exact [runtime payload lock](docs/beta-1/reference/runtime-payload-lock.json) records pinned files, sizes and hashes. The [component metadata](docs/beta-1/reference/component-metadata.json) records shipped dependency declarations. These references are more precise than a manually copied dependency list. Third-party and historical license notices must accompany their matching payloads. + Retained records GeoJSON import datasets; parcels and zone/overlay context; cited rules; questions and answers; review events; selected Meetings history; immutable snapshots. + Output Source-backed parcel context, informational answers, recorded human corrections and reviewed snapshots with stable hashes. -| Data contract | Description | -| --- | --- | -| Input | A supported EPSG:4326 GeoJSON envelope, jurisdiction and dataset metadata, public Code authority and permitted meeting evidence. | -| Retained records | GeoJSON import datasets; parcels and zone/overlay context; cited rules; questions and answers; review events; selected Meetings history; immutable snapshots. | -| Output | Source-backed parcel context, informational answers, recorded human corrections and reviewed snapshots with stable hashes. | -| Connections | Consumes Code authority and permitted Meetings evidence. Supplies permitted snapshots to Records and context to Planning and Permitting. | + Connections Consumes Code authority and permitted Meetings evidence. Supplies permitted snapshots to Records and context to Planning and Permitting. + --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- +Setup and operation -## Setup and operation +1. Obtain the identified signed private candidate and its corresponding-source companion from the beta coordinator. The landing pages in this documentation are not an installer download service. +2. On the intended fresh Windows test installation, verify the MSI hash and publisher signature before installing. Preserve unrelated profiles and recovery material. Installed acceptance for this source candidate remains pending; no in-place legacy upgrade is supported. +3. Launch Townlight under the intended named Windows account. Choose the storage folders. Select Townlight Inspections candidate (inspections-preview) for the bounded desktop composition, including Access and Notice. A narrower default selection will not expose all workspaces. +4. Enter the city profile, time zone and contacts. Create the first named local administrator, sign in and choose protected backup storage. Continue without local AI is valid for the deterministic workflows. +5. Run Health Check and wait for readiness. Open Townlight. In System Health select Finish Records Migration to activate the canonical Python/PostgreSQL runtime. Do not fabricate migration receipts or seed accounts. +6. Create named staff through Settings. Import authorized sources using each product’s source library. All examples in this package are synthetic; they are not municipal authority. +7. Provision Station separately if it is part of the beta exercise. Selecting the desktop composition does not start or configure Station. Configure vision explicitly only if automatic photo drafting is selected. -1. Obtain the identified signed private candidate and its corresponding-source companion from the beta coordinator. The landing pages in this documentation are not an installer download service. -2. On the intended fresh Windows test installation, verify the MSI hash and publisher signature before installing. Preserve unrelated profiles and recovery material. This candidate has fresh-install acceptance; historical in-place upgrades are unverified. -3. Launch Townlight under the intended named Windows account. Choose the storage folders. Select **Townlight Inspections candidate** (`inspections-preview`) for all eight desktop products. A narrower default selection will not expose all workspaces. -4. Enter the city profile, time zone and contacts. Create the first named local administrator, sign in and choose protected backup storage. **Continue without local AI** is valid for the deterministic workflows. -5. Run Health Check and wait for readiness. Open Townlight. In System Health select **Finish Records Migration** to activate the canonical Python/PostgreSQL runtime. Do not fabricate migration receipts or seed accounts. -6. Create named staff through Settings. Import authorized sources using each product’s source library. All examples in this package are synthetic; they are not municipal authority. -7. Provision Station separately if it is part of the beta exercise. Selecting the desktop composition does not start or configure Station. Configure vision explicitly only if automatic photo drafting is selected. +Configuration -## Configuration -### Native deployment configuration +Native deployment configuration -Use Setup, Settings and System Health for supported staff operation. Administrators provision folders, backup storage, named accounts and the city profile. Select `inspections-preview` for the full eight-workspace desktop. Station remains a separate service boundary. Do not use a standalone product’s demo server as a substitute for the installed workspace. +Use Setup, Settings and System Health for supported staff operation. Administrators provision folders, backup storage, named accounts and the city profile. Select inspections-preview for the bounded desktop composition, including Access and Notice. Station remains a separate service boundary. Do not use a standalone product’s demo server as a substitute for the installed workspace. -Technical deployments use `TOWNLIGHT_PRODUCT_PROFILE`, `TOWNLIGHT_PROFILE_ROOT`, `DATABASE_URL`, `CIVICSUITE_RUNTIME_PORT`, `PORTAL_MODE` and the runtime-managed secret files. Treat database URLs and native session proofs as secrets. The installed native domain runtime explicitly refuses non-loopback binding. `PORTAL_MODE=private` is the accepted posture; changing it does not by itself commission an internet portal, authentication provider or reverse proxy. +Technical deployments use TOWNLIGHT_PRODUCT_PROFILE, TOWNLIGHT_PROFILE_ROOT, DATABASE_URL, TOWNLIGHT_RUNTIME_PORT, PORTAL_MODE and the runtime-managed secret files. Treat database URLs and native session proofs as secrets. The installed native domain runtime explicitly refuses non-loopback binding. PORTAL_MODE=private is the accepted posture; changing it does not by itself commission an internet portal, authentication provider or reverse proxy. The isolated documentation exporter sets a fictional profile and unusable synthetic database origin only to read schemas; those values are not deployment configuration. Keep deployment values in the intended process/account scope. An already-running process does not automatically inherit later environment edits. -## API usage -### Native command example +API usage -The following JavaScript belongs in the existing trusted Townlight frontend/development environment with `invoke` imported from `@tauri-apps/api/core`. It is not a command for an arbitrary web page or an instruction for nontechnical staff. IDs must come from records created in an isolated synthetic exercise. +Native command example -```javascript -import { invoke } from '@tauri-apps/api/core'; -const result = await invoke('zoning_domain_request', {request: {operation: 'history', id: questionId}}); -console.log(result); -``` +The following JavaScript belongs in the existing trusted Townlight frontend/development environment with invoke imported from @tauri-apps/api/core. It is not a command for an arbitrary web page or an instruction for nontechnical staff. IDs must come from records created in an isolated synthetic exercise. -### Trusted local HTTP example + import { invoke } from '@tauri-apps/api/core'; + const result = await invoke('zoning_domain_request', {request: {operation: 'history', id: questionId}}); + console.log(result); + +Trusted local HTTP example An administrator/developer can inspect an already-configured isolated runtime from a trusted local process. This PowerShell example reads the signed-in synthetic profile’s existing proof into memory; it does not create a user, seed a session, reveal the proof in output or bypass a permission check. Do not use real city data in development examples. A read response does not prove approval or publication. -```powershell -$profilePath = Join-Path $env:LOCALAPPDATA 'CivicSuite' -$sessionPath = Join-Path $profilePath 'config\local-session.json' -$session = Get-Content -LiteralPath $sessionPath -Raw | ConvertFrom-Json -$headers = @{ 'X-Townlight-Session' = $session.session_hash } -Invoke-RestMethod -Uri 'http://127.0.0.1:15480/desktop/v1/zoning/workspace' -Headers $headers -Remove-Variable session, headers -``` + $profilePath = Join-Path $env:LOCALAPPDATA 'CivicSuite' + $sessionPath = Join-Path $profilePath 'config\local-session.json' + $session = Get-Content -LiteralPath $sessionPath -Raw | ConvertFrom-Json + $headers = @{ 'X-Townlight-Session' = $session.session_hash } + Invoke-RestMethod -Uri 'http://127.0.0.1:15480/desktop/v1/zoning/workspace' -Headers $headers + Remove-Variable session, headers -### Complete synthetic source bundle +Complete synthetic source bundle -The [synthetic Zoning bundle](docs/beta-1/reference/examples/synthetic-geo-bundle.json) is the retained fixture used by the beta staff exercise. It includes the complete supported source envelope rather than a shortened pseudo-payload. Keep its fictional source labels. For Planning, wrap it as `{"bundle": BUNDLE, "expected_previous_revision": null}`; for Permitting use `{"bundle": BUNDLE, "expected_revision": null}`. Code and Zoning take their own complete import envelopes. Replace null with the current expected revision when revising an existing source, as the applicable schema requires. These are import examples, not legal authority or permission to load them into a live city profile. +The synthetic Zoning bundle is the retained fixture used by the beta staff exercise. It includes the complete supported source envelope rather than a shortened pseudo-payload. Keep its fictional source labels. For Planning, wrap it as {"bundle": BUNDLE, "expected_previous_revision": null}; for Permitting use {"bundle": BUNDLE, "expected_revision": null}. Code and Zoning take their own complete import envelopes. Replace null with the current expected revision when revising an existing source, as the applicable schema requires. These are import examples, not legal authority or permission to load them into a live city profile. -### A synthetic write with subsequent readback +A synthetic write with subsequent readback This example demonstrates the existing Meetings HTTP contract in an isolated exercise. It is intentionally fictional. It does not start a service. Its authentication setup is included so it can be run independently under the signed-in synthetic account. If a write times out, inspect current records before repeating it. -```powershell -$profilePath = Join-Path $env:LOCALAPPDATA 'CivicSuite' -$sessionPath = Join-Path $profilePath 'config/local-session.json' -$session = Get-Content -LiteralPath $sessionPath -Raw | ConvertFrom-Json -$headers = @{ 'X-Townlight-Session' = $session.session_hash } -$body = @{ - title = 'Synthetic documentation exercise' - scheduled_start = '2026-11-05T18:00:00-07:00' - location = 'Synthetic room' - meeting_type = 'regular' -} | ConvertTo-Json -$meeting = Invoke-RestMethod -Method Post ` - -Uri 'http://127.0.0.1:15480/desktop/v1/meetings/meetings' ` - -Headers $headers -ContentType 'application/json' -Body $body -Invoke-RestMethod ` - -Uri ('http://127.0.0.1:15480/desktop/v1/meetings/meetings/' + $meeting.id) ` - -Headers $headers -Remove-Variable session, headers -``` + $profilePath = Join-Path $env:LOCALAPPDATA 'CivicSuite' + $sessionPath = Join-Path $profilePath 'config/local-session.json' + $session = Get-Content -LiteralPath $sessionPath -Raw | ConvertFrom-Json + $headers = @{ 'X-Townlight-Session' = $session.session_hash } + $body = @{ + title = 'Synthetic documentation exercise' + scheduled_start = '2026-11-05T18:00:00-07:00' + location = 'Synthetic room' + meeting_type = 'regular' + } | ConvertTo-Json + $meeting = Invoke-RestMethod -Method Post ` + -Uri 'http://127.0.0.1:15480/desktop/v1/meetings/meetings' ` + -Headers $headers -ContentType 'application/json' -Body $body + Invoke-RestMethod ` + -Uri ('http://127.0.0.1:15480/desktop/v1/meetings/meetings/' + $meeting.id) ` + -Headers $headers + Remove-Variable session, headers This write requires Meetings to be enabled and the signed-in staff role to permit it. It is a cross-suite integration example; for this product’s request models, use the complete technical reference below. -## MCP status +MCP status -No direct product MCP server is exposed by the accepted Townlight desktop or Station boundary. Do not configure an invented `townlight mcp` command or assume an AI client has staff permissions. The integration surfaces for this beta are native IPC, the documented HTTP APIs, source bundle imports, exact exports and the existing Station CLI. +No direct product MCP server is exposed by the accepted Townlight desktop or Station boundary. Do not configure an invented townlight mcp command or assume an AI client has staff permissions. The integration surfaces for this beta are native IPC, the documented HTTP APIs, source bundle imports, exact exports and the existing Station CLI. -The bundled transcription code includes a **TextFlowKit MCP adapter** as a separate source capability. It offers job-based `transcribe_media`, `get_transcript`, `list_jobs`, `get_job_status` and `export_transcript`, and additional tools declared in that adapter. It uses stdio first and optional Streamable HTTP, with the MCP SDK as an optional extra. It is not automatically launched, authenticated as Townlight staff or accepted as a Townlight product MCP deployment. This documentation does not add such a service. +The bundled transcription code includes a TextFlowKit MCP adapter as a separate source capability. It offers job-based transcribe_media, get_transcript, list_jobs, get_job_status and export_transcript, and additional tools declared in that adapter. It uses stdio first and optional Streamable HTTP, with the MCP SDK as an optional extra. It is not automatically launched, authenticated as Townlight staff or accepted as a Townlight product MCP deployment. This documentation does not add such a service. For a transcription client already provisioned separately, an illustrative tool call is: -```json -{"name":"get_job_status","arguments":{"job_id":"synthetic-existing-job-id"}} -``` + {"name":"get_job_status","arguments":{"job_id":"synthetic-existing-job-id"}} -Use a job ID returned by that transcription service. This example does not create a Townlight record or bypass its review/Records handoff. The exact optional adapter tool signatures are supplied in the [MCP source reference](docs/beta-1/reference/mcp.html). Station meeting capture does not become live speech recognition because this optional donor adapter exists. +Use a job ID returned by that transcription service. This example does not create a Townlight record or bypass its review/Records handoff. The exact optional adapter tool signatures are supplied in the MCP source reference. Station meeting capture does not become live speech recognition because this optional donor adapter exists. -## Verification and known limits +Verification and known limits -| Product | Recorded result | Precisely exercised | -| --- | --- | --- | -| Zoning | PASS | GeoJSON/PostGIS import, cited dimensional rule, parcel answer, staff review/history/snapshot and native workspace. | + -------------------------------------------------------------------------------------------------------------------------------------------------------------------- + Product Recorded result Precisely exercised + ----------------------- ----------------------- -------------------------------------------------------------------------------------------------------------------- + Zoning PASS GeoJSON/PostGIS import, cited dimensional rule, parcel answer, staff review/history/snapshot and native workspace. + -------------------------------------------------------------------------------------------------------------------------------------------------------------------- These results come from the identified signed candidate’s fresh normal-profile Sandbox exercise: real native IPC/HTTP/PostgreSQL and selected headless controls. All accounts, source bundles and media were synthetic. The guest install/uninstall and recovery passed, and the owned Sandbox stopped. No host installed application or standalone CivicCast was changed. This documentation task reuses those receipts; it does not claim a new software acceptance run. -The [workflow matrix](docs/beta-1/reference/workflow-matrix.json) identifies raw receipt filenames. The [evidence index](docs/beta-1/reference/sandbox-evidence-index.json) retains their original hashes; raw receipts remain in the private beta handoff rather than being silently republished with the documentation site. +The workflow matrix identifies raw receipt filenames. The evidence index retains their original hashes; raw receipts remain in the private beta handoff rather than being silently republished with the documentation site. The limits remain: actual city field acceptance and equipment/network commissioning; Station automatic provisioning/SCM commissioning; every UI/role combination; field recognition accuracy; and historical in-place upgrades are not certified. They are not five invented feature requirements. Fresh-install controlled beta handoff remains the accepted scope. This package makes no city-deployment, publication or general-availability claim. The accepted path is local GeoJSON/PostGIS. It does not establish every ArcGIS, assessor or CKAN connector. Answers and process explanations are informational and do not issue an entitlement or an official zoning determination. -## Development and repository map +Development and repository map -Use the corresponding source for the candidate rather than assuming the public default branch matches it. The source companion contains `installed-owned-source`, product build inputs, desktop Rust/browser sources, locks and `BUILD.md`. It excludes credentials and third-party binary/model payloads. Use the recorded runtime lock when reproducing packaging. +Use the corresponding source for the candidate rather than assuming the public default branch matches it. The source companion contains installed-owned-source, product build inputs, desktop Rust/browser sources, locks and BUILD.md. It excludes credentials and third-party binary/model payloads. Use the recorded runtime lock when reproducing packaging. Relevant source contracts: -- `civiczone/geo_import.py` -- `civiczone/discretionary.py` -- `civicsuite_runtime/zoning_bridge.py` -- `civicsuite_runtime/zoning_records.py` +- townlight_zoning/geo_import.py +- townlight_zoning/discretionary.py +- townlight_runtime/zoning_bridge.py +- townlight_runtime/zoning_records.py -The desktop package defines `npm run build`, `npm test`, `npm run test:browser` and its Tauri command. Python products retain their own `pyproject.toml`, tests and migrations; use the matching checkout’s declared dependencies and test configuration. Do not run a sample server against a production profile. This documentation build validates documentation only and reuses the separately identified installed acceptance; it does not claim a new complete application CI run. +The desktop package defines npm run build, npm test, npm run test:browser and its Tauri command. Python products retain their own pyproject.toml, tests and migrations; use the matching checkout’s declared dependencies and test configuration. Do not run a sample server against a production profile. This documentation build validates documentation only and reuses the separately identified installed acceptance; it does not claim a new complete application CI run. -## Recovery and support +Recovery and support -Save work and use Core’s canonical **Backup Now** before maintenance. That operation stops writers. Preserve the coherent profile/database/document backup and its receipt, then use **Start** to resume. A source export is not a full backup. +Save work and use Core’s canonical Backup Now before maintenance. That operation stops writers. Preserve the coherent profile/database/document backup and its receipt, then use Start to resume. A source export is not a full backup. -Use **Restore Latest Backup** through the supported controls. If the result says **Restore needs service start**, use **Start**, then **Check**, and reopen a known record. Do not repeat restore merely because services need to start. The fresh-profile acceptance verified that a fulfilled request survived restore and a post-backup marker did not. +Use Restore Latest Backup through the supported controls. If the result says Restore needs service start, use Start, then Check, and reopen a known record. Do not repeat restore merely because services need to start. The fresh-profile acceptance verified that a fulfilled request survived restore and a post-backup marker did not. Keep Station’s dedicated database and media evidence together in its own backup. Core’s native-profile backup must not be assumed to include an external Station data directory. Stop writers during a coordinated backup. Preserve failed media attempts and logs. On failure, record the time, selected composition, component/installer versions and exact message. Check System Health for stopped, starting, ready or failed dependencies. Use the existing Retry control after readiness; do not create duplicate business records to refresh a stale view. Share only a redacted diagnostic bundle. Preserve secrets, original evidence, recovery material and unrelated installations. -## License and responsible use +Prepared package installation + +The renamed distributions are not yet published on a package index. Use the matching verified candidate wheel directory, not a renamed historical release URL. Installation of these Python packages is a developer/package check; the signed Windows MSI and its installed acceptance remain separate. + +In a new Windows virtual environment, replace the example wheel-directory path with the directory accompanying this candidate and verify its SHA256 manifest: + + python -m venv .venv + .\.venv\Scripts\Activate.ps1 + $candidateWheels = (Resolve-Path 'C:\path\to\candidate-wheels').Path + python -m pip install (Join-Path $candidateWheels 'townlight_core-1.3.0.dev2-py3-none-any.whl') + python -m pip install (Join-Path $candidateWheels 'townlight_zoning-0.2.3-py3-none-any.whl') + python -c "import townlight_zoning; from importlib.metadata import version; print(version('townlight-zoning'))" + +Expected principal import: townlight_zoning; expected distribution version: 0.2.3. Use a fresh empty database/profile for workflow testing. Existing city data and the previous release remain untouched; no in-place upgrade or old-import compatibility shim is supplied. + +License and responsible use Current owned code is AGPL-3.0-only. Preserve full license, matching corresponding source, dependency notices and historical grants. Terms of use do not remove license rights. Source imports do not confer permission to publish third-party material. Review all automatic drafts and use the separate owning-product decision before official action. CivicCast remains independent. -## Earlier documentation +Earlier documentation -Previous editions are retained under `docs/history/pre-townlight-beta-1/`. They describe their original software and license grants. Use the current Townlight Beta 1 manual for this candidate. +Previous editions are retained under docs/history/pre-townlight-beta-1/. They describe their original software and license grants. Use the current Townlight Beta 1 manual for this candidate. diff --git a/SECURITY.md b/SECURITY.md index 560cc55..e95c7d8 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,5 +1,7 @@ # Security -Townlight Zoning Current version: 0.2.2. This is a narrow truth-repair release with no functional upgrade. The previous v1.0.0 release was published in error and does not prove public-use readiness. Deploy it only for local scaffold evaluation behind the city's trusted access layer, set `CIVICZONE_STAFF_TRUSTED_PROXY_CIDRS` for the reverse proxy allowed to inject staff headers, review local parcel/rule data with planning staff, and route official zoning determinations to municipal staff. +Prepared naming candidate: `townlight-zoning` 0.2.3. Installed acceptance remains pending. + +Townlight Zoning Current version: 0.2.2. This is a narrow truth-repair release with no functional upgrade. The previous v1.0.0 release was published in error and does not prove public-use readiness. Deploy it only for local scaffold evaluation behind the city's trusted access layer, set `TOWNLIGHT_ZONING_STAFF_TRUSTED_PROXY_CIDRS` for the reverse proxy allowed to inject staff headers, review local parcel/rule data with planning staff, and route official zoning determinations to municipal staff. Report suspected vulnerabilities privately to the project maintainer. Do not open public issues containing exploit details, secrets, or sensitive municipal data. diff --git a/USER-MANUAL.docx b/USER-MANUAL.docx index 127ea15..8e7b61c 100644 Binary files a/USER-MANUAL.docx and b/USER-MANUAL.docx differ diff --git a/USER-MANUAL.md b/USER-MANUAL.md index 120afa0..7a6b24b 100644 --- a/USER-MANUAL.md +++ b/USER-MANUAL.md @@ -1,6 +1,6 @@ # Townlight Zoning Manual -**Townlight Beta 1** · Documentation edition 30 October 2026 +**Townlight Beta 1** · Naming candidate documentation edition 2 November 2026 ## Contents @@ -34,23 +34,22 @@ Staff should begin with First run and Daily workflow. Administrators should also | Identity | Value | | --- | --- | -| Public documentation identity | Townlight Beta 1 | -| Installer version | 1.6.0.1 | -| Product component | civiczone 0.2.2 | -| Native desktop source version | 1.6.0-1 | -| Candidate MSI SHA256 | `98bcdef11ebdf5c767f620c904ff49f85115fde3b5c23f62703b111e645aaf86` | -| Corresponding-source SHA256 | `84a23e1297e42d17b16cfc9e51b2dd78bc46414c0de8ad7ebd2466c1a409d06b` | +| Documentation | Townlight Beta 1 naming, Access and Notice candidate | +| Intended installer version | 1.7.0.1; build and acceptance pending | +| Product component | townlight-zoning 0.2.3 | +| Principal import package | townlight_zoning | +| Native desktop source version | 1.7.0-1 | +| Candidate hashes | Pending candidate build, signing and installed acceptance | | Current owned software license | AGPL-3.0-only | -| Supported acceptance profile | Windows x64 fresh install; inspections-preview; separate Station configuration | +| Acceptance composition | Fresh Windows x64 profile; inspections-preview; Station configured separately | - -“Townlight Beta 1” identifies this coordinated beta delivery. It does not renumber the installer, native binary, Python packages or historical receipts. Component versions may differ. This documentation is a later companion to unchanged signed bytes, not a rebuilt installer. Historical release pages and manuals describe their own versions and are not the download instructions for this private candidate. +The naming change advances this package's version and requires a new signed installer and installed acceptance. Those steps and publication remain pending. Historical tags, receipts and archived manuals keep their original names and certify only their identified artifacts. Use an empty database and fresh profile; no in-place legacy upgrade is supported. The approved Windows profile path remains `%LOCALAPPDATA%\CivicSuite`. Preserve existing profiles, data and recovery material. ## First run 1. Obtain the identified signed private candidate and its corresponding-source companion from the beta coordinator. The landing pages in this documentation are not an installer download service. -2. On the intended fresh Windows test installation, verify the MSI hash and publisher signature before installing. Preserve unrelated profiles and recovery material. This candidate has fresh-install acceptance; historical in-place upgrades are unverified. -3. Launch Townlight under the intended named Windows account. Choose the storage folders. Select **Townlight Inspections candidate** (`inspections-preview`) for all eight desktop products. A narrower default selection will not expose all workspaces. +2. On the intended fresh Windows test installation, verify the MSI hash and publisher signature before installing. Preserve unrelated profiles and recovery material. Installed acceptance for this source candidate remains pending; no in-place legacy upgrade is supported. +3. Launch Townlight under the intended named Windows account. Choose the storage folders. Select **Townlight Inspections candidate** (`inspections-preview`) for the bounded desktop composition, including Access and Notice. A narrower default selection will not expose all workspaces. 4. Enter the city profile, time zone and contacts. Create the first named local administrator, sign in and choose protected backup storage. **Continue without local AI** is valid for the deterministic workflows. 5. Run Health Check and wait for readiness. Open Townlight. In System Health select **Finish Records Migration** to activate the canonical Python/PostgreSQL runtime. Do not fabricate migration receipts or seed accounts. 6. Create named staff through Settings. Import authorized sources using each product’s source library. All examples in this package are synthetic; they are not municipal authority. @@ -153,10 +152,10 @@ Check the complete JSON envelope, original hashes and EPSG:4326 geometry before The standalone Zoning application's review/analytics/report routes are documented source capabilities, not extra native desktop screens. In a deployment where its actual staff authentication is already configured: -- Create an ambiguity review with `zone_code`, `question` and `reason` at `/api/v1/civiczone/staff/ambiguity-reviews`. Read its returned ID and list state. Update that ID with `status`, optional `assigned_to` and `resolution`; use `open`, `in_review`, `resolved` or `closed`. Resolving or closing requires a nonempty `resolution`. -- Retain a flagged answer at `/api/v1/civiczone/staff/flagged-answers` with the original question/answer, zone, flag reason and source citations. Use `/{review_id}/improve` with `improved_answer` and `improvement_notes`. Preserve the original and improvement attribution; a correction does not rewrite the imported Code source. -- Read `/api/v1/civiczone/staff/questions/analytics` with the desired `high_volume_threshold` to identify repeated questions and uncertain answers. Analytics counts are review aids, not jurisdictional conclusions. -- Create `/api/v1/civiczone/staff/reports/outline` with a title and actual selected `question_ids`/`queue_item_ids`. Review the resulting outline and citations before incorporating it in a staff report. It is not a filed report or a meeting decision. +- Create an ambiguity review with `zone_code`, `question` and `reason` at `/api/v1/townlight_zoning/staff/ambiguity-reviews`. Read its returned ID and list state. Update that ID with `status`, optional `assigned_to` and `resolution`; use `open`, `in_review`, `resolved` or `closed`. Resolving or closing requires a nonempty `resolution`. +- Retain a flagged answer at `/api/v1/townlight_zoning/staff/flagged-answers` with the original question/answer, zone, flag reason and source citations. Use `/{review_id}/improve` with `improved_answer` and `improvement_notes`. Preserve the original and improvement attribution; a correction does not rewrite the imported Code source. +- Read `/api/v1/townlight_zoning/staff/questions/analytics` with the desired `high_volume_threshold` to identify repeated questions and uncertain answers. Analytics counts are review aids, not jurisdictional conclusions. +- Create `/api/v1/townlight_zoning/staff/reports/outline` with a title and actual selected `question_ids`/`queue_item_ids`. Review the resulting outline and citations before incorporating it in a staff report. It is not a filed report or a meeting decision. A synthetic ambiguity request is: @@ -166,7 +165,7 @@ A synthetic ambiguity request is: Do not send invented staff-role headers or assume these standalone paths exist at the installed desktop origin. The native workspace's supported review/history/snapshot controls continue to use its fixed authenticated bridge. Use the technical supplement to distinguish the two surfaces. -Source contracts: `civicsuite_runtime/zoning_bridge.py`, `civiczone/main.py`, the imported rule/source models and desktop Zoning view. +Source contracts: `townlight_runtime/zoning_bridge.py`, `townlight_zoning/main.py`, the imported rule/source models and desktop Zoning view. ## Technical specifications @@ -186,16 +185,16 @@ Versioned saves use expected prior revision identifiers where defined. Reopen an ### Capacity and platform statements -This beta has synthetic single-profile workflow evidence. It does not have a published benchmark for concurrent staff capacity, minimum RAM/CPU, large-source limits or a field SLA. Do not turn a developer machine’s specification into a supported minimum. Installer size is 2,092,122,112 bytes before installation; allow additional disk for extracted runtime, database, originals, exports, media and backups. Select equipment/storage after sizing those actual workloads. +This beta has synthetic single-profile workflow evidence. It does not have a published benchmark for concurrent staff capacity, minimum RAM/CPU, large-source limits or a field SLA. Do not turn a developer machine’s specification into a supported minimum. The new installer size remains pending its build; allow additional disk for extracted runtime, database, originals, exports, media and backups. Select equipment/storage after sizing those actual workloads. The exact [runtime payload lock](docs/beta-1/reference/runtime-payload-lock.json) records pinned files, sizes and hashes. The [component metadata](docs/beta-1/reference/component-metadata.json) records shipped dependency declarations. These references are more precise than a manually copied dependency list. Third-party and historical license notices must accompany their matching payloads. ## Configuration and administration ### Native deployment configuration -Use Setup, Settings and System Health for supported staff operation. Administrators provision folders, backup storage, named accounts and the city profile. Select `inspections-preview` for the full eight-workspace desktop. Station remains a separate service boundary. Do not use a standalone product’s demo server as a substitute for the installed workspace. +Use Setup, Settings and System Health for supported staff operation. Administrators provision folders, backup storage, named accounts and the city profile. Select `inspections-preview` for the bounded desktop composition, including Access and Notice. Station remains a separate service boundary. Do not use a standalone product’s demo server as a substitute for the installed workspace. -Technical deployments use `TOWNLIGHT_PRODUCT_PROFILE`, `TOWNLIGHT_PROFILE_ROOT`, `DATABASE_URL`, `CIVICSUITE_RUNTIME_PORT`, `PORTAL_MODE` and the runtime-managed secret files. Treat database URLs and native session proofs as secrets. The installed native domain runtime explicitly refuses non-loopback binding. `PORTAL_MODE=private` is the accepted posture; changing it does not by itself commission an internet portal, authentication provider or reverse proxy. +Technical deployments use `TOWNLIGHT_PRODUCT_PROFILE`, `TOWNLIGHT_PROFILE_ROOT`, `DATABASE_URL`, `TOWNLIGHT_RUNTIME_PORT`, `PORTAL_MODE` and the runtime-managed secret files. Treat database URLs and native session proofs as secrets. The installed native domain runtime explicitly refuses non-loopback binding. `PORTAL_MODE=private` is the accepted posture; changing it does not by itself commission an internet portal, authentication provider or reverse proxy. The isolated documentation exporter sets a fictional profile and unusable synthetic database origin only to read schemas; those values are not deployment configuration. Keep deployment values in the intended process/account scope. An already-running process does not automatically inherit later environment edits. diff --git a/USER-MANUAL.pdf b/USER-MANUAL.pdf index bb8e2f6..976f000 100644 Binary files a/USER-MANUAL.pdf and b/USER-MANUAL.pdf differ diff --git a/USER-MANUAL.txt b/USER-MANUAL.txt index 120afa0..f1a96f1 100644 --- a/USER-MANUAL.txt +++ b/USER-MANUAL.txt @@ -1,106 +1,100 @@ -# Townlight Zoning Manual - -**Townlight Beta 1** · Documentation edition 30 October 2026 - -## Contents - -- [Using this manual](#using-this-manual) -- [Beta identity](#beta-identity) -- [First run](#first-run) -- [Daily workflow](#daily-workflow) -- [Connected workflows](#connected-workflows) -- [Architecture](#architecture) -- [Discretionary processes and staff review](#discretionary-processes-and-staff-review) -- [Technical specifications](#technical-specifications) -- [Configuration and administration](#configuration-and-administration) -- [API and integration examples](#api-and-integration-examples) -- [MCP and automation boundary](#mcp-and-automation-boundary) -- [Security and permissions](#security-and-permissions) -- [Backup recovery and maintenance](#backup-recovery-and-maintenance) -- [Troubleshooting](#troubleshooting) -- [Verified workflows and limits](#verified-workflows-and-limits) -- [Terms of service and license](#terms-of-service-and-license) -- [Glossary](#glossary) -- [Alphabetical subject index](#alphabetical-subject-index) -- [Source and document control](#source-and-document-control) - -## Using this manual +Townlight Zoning Manual + +Townlight Beta 1 · Naming candidate documentation edition 2 November 2026 + +Contents + +- Using this manual +- Beta identity +- First run +- Daily workflow +- Connected workflows +- Architecture +- Discretionary processes and staff review +- Technical specifications +- Configuration and administration +- API and integration examples +- MCP and automation boundary +- Security and permissions +- Backup recovery and maintenance +- Troubleshooting +- Verified workflows and limits +- Terms of service and license +- Glossary +- Alphabetical subject index +- Source and document control + +Using this manual Townlight Zoning helps planners, land-use staff and authorized reviewers. Zoning combines local parcel geometry, cited zoning rules and staff review. It retains questions, corrections and snapshots with provenance so downstream staff can identify the precise evidence used. Staff should begin with First run and Daily workflow. Administrators should also read Architecture, Technical specifications, Configuration, Security and Recovery. Developers should use the exact API/data dictionary and examples. The table of contents and alphabetical subject index link to the relevant sections in the HTML edition; the PDF preserves headings and searchable text. An editable Word edition is included with the same documentation companion. -## Beta identity +Beta identity -| Identity | Value | -| --- | --- | -| Public documentation identity | Townlight Beta 1 | -| Installer version | 1.6.0.1 | -| Product component | civiczone 0.2.2 | -| Native desktop source version | 1.6.0-1 | -| Candidate MSI SHA256 | `98bcdef11ebdf5c767f620c904ff49f85115fde3b5c23f62703b111e645aaf86` | -| Corresponding-source SHA256 | `84a23e1297e42d17b16cfc9e51b2dd78bc46414c0de8ad7ebd2466c1a409d06b` | -| Current owned software license | AGPL-3.0-only | -| Supported acceptance profile | Windows x64 fresh install; inspections-preview; separate Station configuration | + ------------------------------------------------------------------------------------------------------------------- + Identity Value + ----------------------------------- ------------------------------------------------------------------------------- + Documentation Townlight Beta 1 naming, Access and Notice candidate + Intended installer version 1.7.0.1; build and acceptance pending -“Townlight Beta 1” identifies this coordinated beta delivery. It does not renumber the installer, native binary, Python packages or historical receipts. Component versions may differ. This documentation is a later companion to unchanged signed bytes, not a rebuilt installer. Historical release pages and manuals describe their own versions and are not the download instructions for this private candidate. + Product component townlight-zoning 0.2.3 -## First run + Principal import package townlight_zoning -1. Obtain the identified signed private candidate and its corresponding-source companion from the beta coordinator. The landing pages in this documentation are not an installer download service. -2. On the intended fresh Windows test installation, verify the MSI hash and publisher signature before installing. Preserve unrelated profiles and recovery material. This candidate has fresh-install acceptance; historical in-place upgrades are unverified. -3. Launch Townlight under the intended named Windows account. Choose the storage folders. Select **Townlight Inspections candidate** (`inspections-preview`) for all eight desktop products. A narrower default selection will not expose all workspaces. -4. Enter the city profile, time zone and contacts. Create the first named local administrator, sign in and choose protected backup storage. **Continue without local AI** is valid for the deterministic workflows. -5. Run Health Check and wait for readiness. Open Townlight. In System Health select **Finish Records Migration** to activate the canonical Python/PostgreSQL runtime. Do not fabricate migration receipts or seed accounts. -6. Create named staff through Settings. Import authorized sources using each product’s source library. All examples in this package are synthetic; they are not municipal authority. -7. Provision Station separately if it is part of the beta exercise. Selecting the desktop composition does not start or configure Station. Configure vision explicitly only if automatic photo drafting is selected. + Native desktop source version 1.7.0-1 -## Daily workflow + Candidate hashes Pending candidate build, signing and installed acceptance - + Current owned software license AGPL-3.0-only -### 1. Prepare parcel data + Acceptance composition Fresh Windows x64 profile; inspections-preview; Station configured separately + ------------------------------------------------------------------------------------------------------------------- -Use the complete supported bundle, including jurisdiction, dataset metadata and original hashes. The coordinates must be EPSG:4326. A loose geometry file is not the full source envelope. +The naming change advances this package’s version and requires a new signed installer and installed acceptance. Those steps and publication remain pending. Historical tags, receipts and archived manuals keep their original names and certify only their identified artifacts. Use an empty database and fresh profile; no in-place legacy upgrade is supported. The approved Windows profile path remains %LOCALAPPDATA%\CivicSuite. Preserve existing profiles, data and recovery material. - +First run -### 2. Import and inspect +1. Obtain the identified signed private candidate and its corresponding-source companion from the beta coordinator. The landing pages in this documentation are not an installer download service. +2. On the intended fresh Windows test installation, verify the MSI hash and publisher signature before installing. Preserve unrelated profiles and recovery material. Installed acceptance for this source candidate remains pending; no in-place legacy upgrade is supported. +3. Launch Townlight under the intended named Windows account. Choose the storage folders. Select Townlight Inspections candidate (inspections-preview) for the bounded desktop composition, including Access and Notice. A narrower default selection will not expose all workspaces. +4. Enter the city profile, time zone and contacts. Create the first named local administrator, sign in and choose protected backup storage. Continue without local AI is valid for the deterministic workflows. +5. Run Health Check and wait for readiness. Open Townlight. In System Health select Finish Records Migration to activate the canonical Python/PostgreSQL runtime. Do not fabricate migration receipts or seed accounts. +6. Create named staff through Settings. Import authorized sources using each product’s source library. All examples in this package are synthetic; they are not municipal authority. +7. Provision Station separately if it is part of the beta exercise. Selecting the desktop composition does not start or configure Station. Configure vision explicitly only if automatic photo drafting is selected. -Check the complete source envelope before selecting Import parcel dataset. That control submits directly; inspect the saved validation/provenance result afterward. Correct a refused source bundle and preserve the evidence. Do not force acceptance by editing SQL. +Daily workflow - +1. Prepare parcel data -### 3. Register cited rules +Use the complete supported bundle, including jurisdiction, dataset metadata and original hashes. The coordinates must be EPSG:4326. A loose geometry file is not the full source envelope. -Associate the zone, rule kind/key and value with the relevant public Code section. Inspect overlays and effective context. Leave missing authority visible for planner review. +2. Import and inspect - +Check the complete source envelope before selecting Import parcel dataset. That control submits directly; inspect the saved validation/provenance result afterward. Correct a refused source bundle and preserve the evidence. Do not force acceptance by editing SQL. -### 4. Ask a parcel question +3. Register cited rules -Look up the intended parcel and ask the supported question. Read the returned citation, applicability and disclaimer. Do not present an uncertain answer as an official decision. +Associate the zone, rule kind/key and value with the relevant public Code section. Inspect overlays and effective context. Leave missing authority visible for planner review. - +4. Ask a parcel question -### 5. Record review and context +Look up the intended parcel and ask the supported question. Read the returned citation, applicability and disclaimer. Do not present an uncertain answer as an official decision. -Record a correction and its reason when needed. Select permitted Meetings history explicitly. Preserve the question/review history and distinguish staff-only precedent from public material. +5. Record review and context - +Record a correction and its reason when needed. Select permitted Meetings history explicitly. Preserve the question/review history and distinguish staff-only precedent from public material. -### 6. Create a snapshot +6. Create a snapshot Review the audience and exact content before creating the immutable snapshot. A public snapshot must satisfy its permitted-source contract; choosing a public label does not sanitize private notes. - - -### 7. Use it downstream +7. Use it downstream Select the exact snapshot for Records or the permitted provider path. The receiving workflow rechecks visibility, source identity and hash before retaining or exporting it. -### Working safely +Working safely Use your own named account and save before leaving a screen. A saved draft is durable; unsaved form text may not be. If a write has an unknown result, reopen its record before repeating it. @@ -110,169 +104,159 @@ Keep originals and derivatives separate. Review the intended audience before exp Drafting, review, approval, attachment, export, fulfillment and publication are separate operations. A Townlight workpaper does not itself adopt law, issue a permit, impose a fine or release a records response. The responsible staff member records the applicable decision. -## Connected workflows +Connected workflows Consumes Code authority and permitted Meetings evidence. Supplies permitted snapshots to Records and context to Planning and Permitting. + ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- + Direction Material + ----------------------------------- ---------------------------------------------------------------------------------------------------------------------------------- + Input A supported EPSG:4326 GeoJSON envelope, jurisdiction and dataset metadata, public Code authority and permitted meeting evidence. -| Direction | Material | -| --- | --- | -| Input | A supported EPSG:4326 GeoJSON envelope, jurisdiction and dataset metadata, public Code authority and permitted meeting evidence. | -| Output | Source-backed parcel context, informational answers, recorded human corrections and reviewed snapshots with stable hashes. | - + Output Source-backed parcel context, informational answers, recorded human corrections and reviewed snapshots with stable hashes. + ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- -### Product boundary +Product boundary The accepted path is local GeoJSON/PostGIS. It does not establish every ArcGIS, assessor or CKAN connector. Answers and process explanations are informational and do not issue an entitlement or an official zoning determination. -## Architecture +Architecture -![Townlight Zoning architecture and evidence flow](docs/beta-1/assets/zoning-architecture.svg) +[Townlight Zoning architecture and evidence flow] The drawing shows the principal staff/evidence path. Native commands carry trusted identity to Python business services; PostgreSQL and retained original files hold durable state. A downstream copy does not silently transfer decision authority. Station has its own configured authority/media boundary, database and mutable files. The connected-workflow text supplies the drawing’s reading order and accessibility alternative. -## Discretionary processes and staff review +Discretionary processes and staff review -### Explain the cited process +Explain the cited process -In the existing Zoning workspace, complete **Variance, conditional use or nonconformity question**. Supply the applicable process **Code section**, **zone code**, optional comma-separated **standard to cite**, and optional **observed condition**, for example `front_setback=8 feet`. Select **Explain the cited process**. Choose actual imported public authority; the synthetic values below require matching synthetic sources to return supported guidance. +In the existing Zoning workspace, complete Variance, conditional use or nonconformity question. Supply the applicable process Code section, zone code, optional comma-separated standard to cite, and optional observed condition, for example front_setback=8 feet. Select Explain the cited process. Choose actual imported public authority; the synthetic values below require matching synthetic sources to return supported guidance. -The mounted API is `POST /desktop/v1/zoning/standards/process-explanation` under the normal authenticated staff session. Its equivalent request body is: +The mounted API is POST /desktop/v1/zoning/standards/process-explanation under the normal authenticated staff session. Its equivalent request body is: -```json -{"question":"Explain the synthetic variance process","process_section":"18.20.050","zone_code":"SYN-R","rule_types":["front_setback"],"observed":{"front_setback":"8 feet"}} -``` + {"question":"Explain the synthetic variance process","process_section":"18.20.050","zone_code":"SYN-R","rule_types":["front_setback"],"observed":{"front_setback":"8 feet"}} Read process citations and each cited standard independently. The output can explain a verified process while reporting unavailable standards or review flags. A difference between an observation and a cited standard is an informational flag; it is not a variance finding, approval, nonconformity determination or substitute for planner review. If no relevant authority is available, obtain the source or leave the item unavailable. Do not attach an unrelated citation to a proposed requirement. -### Keep parcel import and inspection in the right order +Keep parcel import and inspection in the right order -Check the complete JSON envelope, original hashes and EPSG:4326 geometry before submitting **Import parcel dataset**. That control sends the import directly; it does not open a separate preview/commit screen. Inspect the returned validation/provenance and saved dataset. The browser refuses bundle files larger than 20 MiB; valid geometry and metadata remain subject to server validation. Correct the source bundle after a refusal and retain earlier evidence rather than forcing SQL changes. +Check the complete JSON envelope, original hashes and EPSG:4326 geometry before submitting Import parcel dataset. That control sends the import directly; it does not open a separate preview/commit screen. Inspect the returned validation/provenance and saved dataset. The browser refuses bundle files larger than 20 MiB; valid geometry and metadata remain subject to server validation. Correct the source bundle after a refusal and retain earlier evidence rather than forcing SQL changes. -### Use the existing specialist review contracts +Use the existing specialist review contracts -The standalone Zoning application's review/analytics/report routes are documented source capabilities, not extra native desktop screens. In a deployment where its actual staff authentication is already configured: +The standalone Zoning application’s review/analytics/report routes are documented source capabilities, not extra native desktop screens. In a deployment where its actual staff authentication is already configured: -- Create an ambiguity review with `zone_code`, `question` and `reason` at `/api/v1/civiczone/staff/ambiguity-reviews`. Read its returned ID and list state. Update that ID with `status`, optional `assigned_to` and `resolution`; use `open`, `in_review`, `resolved` or `closed`. Resolving or closing requires a nonempty `resolution`. -- Retain a flagged answer at `/api/v1/civiczone/staff/flagged-answers` with the original question/answer, zone, flag reason and source citations. Use `/{review_id}/improve` with `improved_answer` and `improvement_notes`. Preserve the original and improvement attribution; a correction does not rewrite the imported Code source. -- Read `/api/v1/civiczone/staff/questions/analytics` with the desired `high_volume_threshold` to identify repeated questions and uncertain answers. Analytics counts are review aids, not jurisdictional conclusions. -- Create `/api/v1/civiczone/staff/reports/outline` with a title and actual selected `question_ids`/`queue_item_ids`. Review the resulting outline and citations before incorporating it in a staff report. It is not a filed report or a meeting decision. +- Create an ambiguity review with zone_code, question and reason at /api/v1/townlight_zoning/staff/ambiguity-reviews. Read its returned ID and list state. Update that ID with status, optional assigned_to and resolution; use open, in_review, resolved or closed. Resolving or closing requires a nonempty resolution. +- Retain a flagged answer at /api/v1/townlight_zoning/staff/flagged-answers with the original question/answer, zone, flag reason and source citations. Use /{review_id}/improve with improved_answer and improvement_notes. Preserve the original and improvement attribution; a correction does not rewrite the imported Code source. +- Read /api/v1/townlight_zoning/staff/questions/analytics with the desired high_volume_threshold to identify repeated questions and uncertain answers. Analytics counts are review aids, not jurisdictional conclusions. +- Create /api/v1/townlight_zoning/staff/reports/outline with a title and actual selected question_ids/queue_item_ids. Review the resulting outline and citations before incorporating it in a staff report. It is not a filed report or a meeting decision. A synthetic ambiguity request is: -```json -{"zone_code":"SYN-R","question":"Which retained setback rule applies?","reason":"Synthetic overlay ambiguity requires planner review"} -``` + {"zone_code":"SYN-R","question":"Which retained setback rule applies?","reason":"Synthetic overlay ambiguity requires planner review"} -Do not send invented staff-role headers or assume these standalone paths exist at the installed desktop origin. The native workspace's supported review/history/snapshot controls continue to use its fixed authenticated bridge. Use the technical supplement to distinguish the two surfaces. +Do not send invented staff-role headers or assume these standalone paths exist at the installed desktop origin. The native workspace’s supported review/history/snapshot controls continue to use its fixed authenticated bridge. Use the technical supplement to distinguish the two surfaces. -Source contracts: `civicsuite_runtime/zoning_bridge.py`, `civiczone/main.py`, the imported rule/source models and desktop Zoning view. +Source contracts: townlight_runtime/zoning_bridge.py, townlight_zoning/main.py, the imported rule/source models and desktop Zoning view. +Technical specifications -## Technical specifications -### Runtime and storage +Runtime and storage -The accepted package targets **Windows x64 fresh installation**. Its native shell uses **Rust 2021, Tauri 2 and Microsoft WebView2**; browser assets are JavaScript built with **Vite 8.1.6**. This describes the native desktop frontend; Station has a separate React operator, specified below or in its product manual. Canonical business workflows use bundled **CPython 3.13.5, FastAPI, Pydantic, SQLAlchemy and Alembic**, with **PostgreSQL 17 / PostGIS** and managed original files. The installed runtime tested here contains FastAPI 0.162.0. Package minimum Python requirements can differ from the bundled executable; the metadata reference preserves both. No stack rewrite is implied by the beta label. +The accepted package targets Windows x64 fresh installation. Its native shell uses Rust 2021, Tauri 2 and Microsoft WebView2; browser assets are JavaScript built with Vite 8.1.6. This describes the native desktop frontend; Station has a separate React operator, specified below or in its product manual. Canonical business workflows use bundled CPython 3.13.5, FastAPI, Pydantic, SQLAlchemy and Alembic, with PostgreSQL 17 / PostGIS and managed original files. The installed runtime tested here contains FastAPI 0.162.0. Package minimum Python requirements can differ from the bundled executable; the metadata reference preserves both. No stack rewrite is implied by the beta label. -The native transport is fixed to loopback `127.0.0.1:15480`; PostgreSQL uses the configured local runtime port (default `15432`). Optional local model service defaults to `127.0.0.1:15434`. Those are deployment defaults, not internet endpoints. The runtime has health, module and readiness endpoints; readiness is stronger than process existence. The task queue is the existing local Core task infrastructure, not an assertion that a separate Redis service is required for this desktop composition. +The native transport is fixed to loopback 127.0.0.1:15480; PostgreSQL uses the configured local runtime port (default 15432). Optional local model service defaults to 127.0.0.1:15434. Those are deployment defaults, not internet endpoints. The runtime has health, module and readiness endpoints; readiness is stronger than process existence. The task queue is the existing local Core task infrastructure, not an assertion that a separate Redis service is required for this desktop composition. -The default native profile is `%LOCALAPPDATA%\CivicSuite`; the historical directory name remains part of compatibility. Do not rename it to Townlight. A configured `TOWNLIGHT_PROFILE_ROOT` must be absolute. Local configuration and secrets live under that profile; protected managed files and database state must be backed up coherently. Source/runtime identity is distinct from a product’s display label. +The default native profile is %LOCALAPPDATA%\CivicSuite; the historical directory name remains part of compatibility. Do not rename it to Townlight. A configured TOWNLIGHT_PROFILE_ROOT must be absolute. Local configuration and secrets live under that profile; protected managed files and database state must be backed up coherently. Source/runtime identity is distinct from a product’s display label. -### Data and consistency +Data and consistency GeoJSON import datasets; parcels and zone/overlay context; cited rules; questions and answers; review events; selected Meetings history; immutable snapshots. Versioned saves use expected prior revision identifiers where defined. Reopen and reconcile on conflict. Exact exports and handoffs use source IDs, current visibility, revision and SHA256. Review belongs to the saved revision and does not transfer silently to edited text. Database changes use the owning product’s migrations; a request or readiness check is not an authorization to mutate schema. -### Capacity and platform statements +Capacity and platform statements + +This beta has synthetic single-profile workflow evidence. It does not have a published benchmark for concurrent staff capacity, minimum RAM/CPU, large-source limits or a field SLA. Do not turn a developer machine’s specification into a supported minimum. The new installer size remains pending its build; allow additional disk for extracted runtime, database, originals, exports, media and backups. Select equipment/storage after sizing those actual workloads. -This beta has synthetic single-profile workflow evidence. It does not have a published benchmark for concurrent staff capacity, minimum RAM/CPU, large-source limits or a field SLA. Do not turn a developer machine’s specification into a supported minimum. Installer size is 2,092,122,112 bytes before installation; allow additional disk for extracted runtime, database, originals, exports, media and backups. Select equipment/storage after sizing those actual workloads. +The exact runtime payload lock records pinned files, sizes and hashes. The component metadata records shipped dependency declarations. These references are more precise than a manually copied dependency list. Third-party and historical license notices must accompany their matching payloads. -The exact [runtime payload lock](docs/beta-1/reference/runtime-payload-lock.json) records pinned files, sizes and hashes. The [component metadata](docs/beta-1/reference/component-metadata.json) records shipped dependency declarations. These references are more precise than a manually copied dependency list. Third-party and historical license notices must accompany their matching payloads. +Configuration and administration -## Configuration and administration -### Native deployment configuration +Native deployment configuration -Use Setup, Settings and System Health for supported staff operation. Administrators provision folders, backup storage, named accounts and the city profile. Select `inspections-preview` for the full eight-workspace desktop. Station remains a separate service boundary. Do not use a standalone product’s demo server as a substitute for the installed workspace. +Use Setup, Settings and System Health for supported staff operation. Administrators provision folders, backup storage, named accounts and the city profile. Select inspections-preview for the bounded desktop composition, including Access and Notice. Station remains a separate service boundary. Do not use a standalone product’s demo server as a substitute for the installed workspace. -Technical deployments use `TOWNLIGHT_PRODUCT_PROFILE`, `TOWNLIGHT_PROFILE_ROOT`, `DATABASE_URL`, `CIVICSUITE_RUNTIME_PORT`, `PORTAL_MODE` and the runtime-managed secret files. Treat database URLs and native session proofs as secrets. The installed native domain runtime explicitly refuses non-loopback binding. `PORTAL_MODE=private` is the accepted posture; changing it does not by itself commission an internet portal, authentication provider or reverse proxy. +Technical deployments use TOWNLIGHT_PRODUCT_PROFILE, TOWNLIGHT_PROFILE_ROOT, DATABASE_URL, TOWNLIGHT_RUNTIME_PORT, PORTAL_MODE and the runtime-managed secret files. Treat database URLs and native session proofs as secrets. The installed native domain runtime explicitly refuses non-loopback binding. PORTAL_MODE=private is the accepted posture; changing it does not by itself commission an internet portal, authentication provider or reverse proxy. The isolated documentation exporter sets a fictional profile and unusable synthetic database origin only to read schemas; those values are not deployment configuration. Keep deployment values in the intended process/account scope. An already-running process does not automatically inherit later environment edits. -## API and integration examples -### Native command example +API and integration examples -The following JavaScript belongs in the existing trusted Townlight frontend/development environment with `invoke` imported from `@tauri-apps/api/core`. It is not a command for an arbitrary web page or an instruction for nontechnical staff. IDs must come from records created in an isolated synthetic exercise. +Native command example -```javascript -import { invoke } from '@tauri-apps/api/core'; -const result = await invoke('zoning_domain_request', {request: {operation: 'history', id: questionId}}); -console.log(result); -``` +The following JavaScript belongs in the existing trusted Townlight frontend/development environment with invoke imported from @tauri-apps/api/core. It is not a command for an arbitrary web page or an instruction for nontechnical staff. IDs must come from records created in an isolated synthetic exercise. -### Trusted local HTTP example + import { invoke } from '@tauri-apps/api/core'; + const result = await invoke('zoning_domain_request', {request: {operation: 'history', id: questionId}}); + console.log(result); + +Trusted local HTTP example An administrator/developer can inspect an already-configured isolated runtime from a trusted local process. This PowerShell example reads the signed-in synthetic profile’s existing proof into memory; it does not create a user, seed a session, reveal the proof in output or bypass a permission check. Do not use real city data in development examples. A read response does not prove approval or publication. -```powershell -$profilePath = Join-Path $env:LOCALAPPDATA 'CivicSuite' -$sessionPath = Join-Path $profilePath 'config\local-session.json' -$session = Get-Content -LiteralPath $sessionPath -Raw | ConvertFrom-Json -$headers = @{ 'X-Townlight-Session' = $session.session_hash } -Invoke-RestMethod -Uri 'http://127.0.0.1:15480/desktop/v1/zoning/workspace' -Headers $headers -Remove-Variable session, headers -``` + $profilePath = Join-Path $env:LOCALAPPDATA 'CivicSuite' + $sessionPath = Join-Path $profilePath 'config\local-session.json' + $session = Get-Content -LiteralPath $sessionPath -Raw | ConvertFrom-Json + $headers = @{ 'X-Townlight-Session' = $session.session_hash } + Invoke-RestMethod -Uri 'http://127.0.0.1:15480/desktop/v1/zoning/workspace' -Headers $headers + Remove-Variable session, headers -### Complete synthetic source bundle +Complete synthetic source bundle -The [synthetic Zoning bundle](docs/beta-1/reference/examples/synthetic-geo-bundle.json) is the retained fixture used by the beta staff exercise. It includes the complete supported source envelope rather than a shortened pseudo-payload. Keep its fictional source labels. For Planning, wrap it as `{"bundle": BUNDLE, "expected_previous_revision": null}`; for Permitting use `{"bundle": BUNDLE, "expected_revision": null}`. Code and Zoning take their own complete import envelopes. Replace null with the current expected revision when revising an existing source, as the applicable schema requires. These are import examples, not legal authority or permission to load them into a live city profile. +The synthetic Zoning bundle is the retained fixture used by the beta staff exercise. It includes the complete supported source envelope rather than a shortened pseudo-payload. Keep its fictional source labels. For Planning, wrap it as {"bundle": BUNDLE, "expected_previous_revision": null}; for Permitting use {"bundle": BUNDLE, "expected_revision": null}. Code and Zoning take their own complete import envelopes. Replace null with the current expected revision when revising an existing source, as the applicable schema requires. These are import examples, not legal authority or permission to load them into a live city profile. -### A synthetic write with subsequent readback +A synthetic write with subsequent readback This example demonstrates the existing Meetings HTTP contract in an isolated exercise. It is intentionally fictional. It does not start a service. Its authentication setup is included so it can be run independently under the signed-in synthetic account. If a write times out, inspect current records before repeating it. -```powershell -$profilePath = Join-Path $env:LOCALAPPDATA 'CivicSuite' -$sessionPath = Join-Path $profilePath 'config/local-session.json' -$session = Get-Content -LiteralPath $sessionPath -Raw | ConvertFrom-Json -$headers = @{ 'X-Townlight-Session' = $session.session_hash } -$body = @{ - title = 'Synthetic documentation exercise' - scheduled_start = '2026-11-05T18:00:00-07:00' - location = 'Synthetic room' - meeting_type = 'regular' -} | ConvertTo-Json -$meeting = Invoke-RestMethod -Method Post ` - -Uri 'http://127.0.0.1:15480/desktop/v1/meetings/meetings' ` - -Headers $headers -ContentType 'application/json' -Body $body -Invoke-RestMethod ` - -Uri ('http://127.0.0.1:15480/desktop/v1/meetings/meetings/' + $meeting.id) ` - -Headers $headers -Remove-Variable session, headers -``` + $profilePath = Join-Path $env:LOCALAPPDATA 'CivicSuite' + $sessionPath = Join-Path $profilePath 'config/local-session.json' + $session = Get-Content -LiteralPath $sessionPath -Raw | ConvertFrom-Json + $headers = @{ 'X-Townlight-Session' = $session.session_hash } + $body = @{ + title = 'Synthetic documentation exercise' + scheduled_start = '2026-11-05T18:00:00-07:00' + location = 'Synthetic room' + meeting_type = 'regular' + } | ConvertTo-Json + $meeting = Invoke-RestMethod -Method Post ` + -Uri 'http://127.0.0.1:15480/desktop/v1/meetings/meetings' ` + -Headers $headers -ContentType 'application/json' -Body $body + Invoke-RestMethod ` + -Uri ('http://127.0.0.1:15480/desktop/v1/meetings/meetings/' + $meeting.id) ` + -Headers $headers + Remove-Variable session, headers This write requires Meetings to be enabled and the signed-in staff role to permit it. It is a cross-suite integration example; for this product’s request models, use the complete technical reference below. -### Complete technical contract +Complete technical contract -Read the [Zoning API reference](docs/beta-1/api/zoning.html) for every documented operation, request field, constraint, response declaration and source supplement. Download the [OpenAPI JSON](docs/beta-1/api/zoning-openapi.json) for tools. For Station this is the suite-side schema only; its separate service contract is documented in the API supplement. The [reference directory](docs/beta-1/reference/index.html) includes configuration/source inventories, dependency declarations, native command contracts, MCP signatures and candidate evidence. +Read the Zoning API reference for every documented operation, request field, constraint, response declaration and source supplement. Download the OpenAPI JSON for tools. For Station this is the suite-side schema only; its separate service contract is documented in the API supplement. The reference directory includes configuration/source inventories, dependency declarations, native command contracts, MCP signatures and candidate evidence. -## MCP and automation boundary +MCP and automation boundary -No direct product MCP server is exposed by the accepted Townlight desktop or Station boundary. Do not configure an invented `townlight mcp` command or assume an AI client has staff permissions. The integration surfaces for this beta are native IPC, the documented HTTP APIs, source bundle imports, exact exports and the existing Station CLI. +No direct product MCP server is exposed by the accepted Townlight desktop or Station boundary. Do not configure an invented townlight mcp command or assume an AI client has staff permissions. The integration surfaces for this beta are native IPC, the documented HTTP APIs, source bundle imports, exact exports and the existing Station CLI. -The bundled transcription code includes a **TextFlowKit MCP adapter** as a separate source capability. It offers job-based `transcribe_media`, `get_transcript`, `list_jobs`, `get_job_status` and `export_transcript`, and additional tools declared in that adapter. It uses stdio first and optional Streamable HTTP, with the MCP SDK as an optional extra. It is not automatically launched, authenticated as Townlight staff or accepted as a Townlight product MCP deployment. This documentation does not add such a service. +The bundled transcription code includes a TextFlowKit MCP adapter as a separate source capability. It offers job-based transcribe_media, get_transcript, list_jobs, get_job_status and export_transcript, and additional tools declared in that adapter. It uses stdio first and optional Streamable HTTP, with the MCP SDK as an optional extra. It is not automatically launched, authenticated as Townlight staff or accepted as a Townlight product MCP deployment. This documentation does not add such a service. For a transcription client already provisioned separately, an illustrative tool call is: -```json -{"name":"get_job_status","arguments":{"job_id":"synthetic-existing-job-id"}} -``` - -Use a job ID returned by that transcription service. This example does not create a Townlight record or bypass its review/Records handoff. The exact optional adapter tool signatures are supplied in the [MCP source reference](docs/beta-1/reference/mcp.html). Station meeting capture does not become live speech recognition because this optional donor adapter exists. + {"name":"get_job_status","arguments":{"job_id":"synthetic-existing-job-id"}} -## Security and permissions +Use a job ID returned by that transcription service. This example does not create a Townlight record or bypass its review/Records handoff. The exact optional adapter tool signatures are supplied in the MCP source reference. Station meeting capture does not become live speech recognition because this optional donor adapter exists. +Security and permissions Use your own named account and save before leaving a screen. A saved draft is durable; unsaved form text may not be. If a write has an unknown result, reopen its record before repeating it. @@ -286,147 +270,181 @@ The native session is validated and mapped to a persisted SQL identity. An edita Use protected local folders, account permissions and credential storage. Never include the native session file, database passwords, provider keys or unredacted support bundles in a public issue or generated public documentation. A local public view is not automatically a secured internet deployment. Keep network exposure and real equipment acceptance specific to the chosen beta site. -## Backup recovery and maintenance +Backup recovery and maintenance -Save work and use Core’s canonical **Backup Now** before maintenance. That operation stops writers. Preserve the coherent profile/database/document backup and its receipt, then use **Start** to resume. A source export is not a full backup. +Save work and use Core’s canonical Backup Now before maintenance. That operation stops writers. Preserve the coherent profile/database/document backup and its receipt, then use Start to resume. A source export is not a full backup. -Use **Restore Latest Backup** through the supported controls. If the result says **Restore needs service start**, use **Start**, then **Check**, and reopen a known record. Do not repeat restore merely because services need to start. The fresh-profile acceptance verified that a fulfilled request survived restore and a post-backup marker did not. +Use Restore Latest Backup through the supported controls. If the result says Restore needs service start, use Start, then Check, and reopen a known record. Do not repeat restore merely because services need to start. The fresh-profile acceptance verified that a fulfilled request survived restore and a post-backup marker did not. Keep Station’s dedicated database and media evidence together in its own backup. Core’s native-profile backup must not be assumed to include an external Station data directory. Stop writers during a coordinated backup. Preserve failed media attempts and logs. On failure, record the time, selected composition, component/installer versions and exact message. Check System Health for stopped, starting, ready or failed dependencies. Use the existing Retry control after readiness; do not create duplicate business records to refresh a stale view. Share only a redacted diagnostic bundle. Preserve secrets, original evidence, recovery material and unrelated installations. -## Troubleshooting +Troubleshooting + + --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + Symptom Likely meaning Next action + ----------------------------- ------------------------------------------------------------------------ -------------------------------------------------------------------------------------------------- + Workspace absent Wrong product composition or unavailable canonical runtime. Check selected composition; activate through Finish Records Migration; wait for readiness. + + Cannot sign in / 401 Missing or expired named account session. Sign in normally; reopen a Station launch ticket if applicable. + + Permission denied / 403 Account, module, source or browser-origin permission. Ask the authorized administrator to inspect the intended permission; do not invent role headers. + + Save conflict / 409 The saved revision, expected source hash or lifecycle changed. Keep edits, reopen current state and reconcile deliberately. + + Invalid input / 422 Required field, format, geometry, source envelope or state is invalid. Read the field detail and correct the input/source; preserve originals. -| Symptom | Likely meaning | Next action | -| --- | --- | --- | -| Workspace absent | Wrong product composition or unavailable canonical runtime. | Check selected composition; activate through Finish Records Migration; wait for readiness. | -| Cannot sign in / 401 | Missing or expired named account session. | Sign in normally; reopen a Station launch ticket if applicable. | -| Permission denied / 403 | Account, module, source or browser-origin permission. | Ask the authorized administrator to inspect the intended permission; do not invent role headers. | -| Save conflict / 409 | The saved revision, expected source hash or lifecycle changed. | Keep edits, reopen current state and reconcile deliberately. | -| Invalid input / 422 | Required field, format, geometry, source envelope or state is invalid. | Read the field detail and correct the input/source; preserve originals. | -| Service unavailable / 503 | Database, schema, connected source or configuration unavailable. | Inspect System Health and the named dependency. Preserve work; retry only after readiness. | -| Export refused | Missing exact review, approval, audience or source authorization. | Read the refusal and complete the owning product’s explicit decision. | -| Restore needs service start | The snapshot was restored but services have not resumed. | Use Start, then Check and verify a saved record; do not blindly repeat restore. | + Service unavailable / 503 Database, schema, connected source or configuration unavailable. Inspect System Health and the named dependency. Preserve work; retry only after readiness. + Export refused Missing exact review, approval, audience or source authorization. Read the refusal and complete the owning product’s explicit decision. -## Verified workflows and limits + Restore needs service start The snapshot was restored but services have not resumed. Use Start, then Check and verify a saved record; do not blindly repeat restore. + --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -| Product | Recorded result | Precisely exercised | -| --- | --- | --- | -| Zoning | PASS | GeoJSON/PostGIS import, cited dimensional rule, parcel answer, staff review/history/snapshot and native workspace. | +Verified workflows and limits + -------------------------------------------------------------------------------------------------------------------------------------------------------------------- + Product Recorded result Precisely exercised + ----------------------- ----------------------- -------------------------------------------------------------------------------------------------------------------- + Zoning PASS GeoJSON/PostGIS import, cited dimensional rule, parcel answer, staff review/history/snapshot and native workspace. + + -------------------------------------------------------------------------------------------------------------------------------------------------------------------- These results come from the identified signed candidate’s fresh normal-profile Sandbox exercise: real native IPC/HTTP/PostgreSQL and selected headless controls. All accounts, source bundles and media were synthetic. The guest install/uninstall and recovery passed, and the owned Sandbox stopped. No host installed application or standalone CivicCast was changed. This documentation task reuses those receipts; it does not claim a new software acceptance run. -The [workflow matrix](docs/beta-1/reference/workflow-matrix.json) identifies raw receipt filenames. The [evidence index](docs/beta-1/reference/sandbox-evidence-index.json) retains their original hashes; raw receipts remain in the private beta handoff rather than being silently republished with the documentation site. +The workflow matrix identifies raw receipt filenames. The evidence index retains their original hashes; raw receipts remain in the private beta handoff rather than being silently republished with the documentation site. The limits remain: actual city field acceptance and equipment/network commissioning; Station automatic provisioning/SCM commissioning; every UI/role combination; field recognition accuracy; and historical in-place upgrades are not certified. They are not five invented feature requirements. Fresh-install controlled beta handoff remains the accepted scope. This package makes no city-deployment, publication or general-availability claim. -## Terms of service and license +Terms of service and license -### Scope and status +Scope and status These terms describe the Townlight Beta 1 software and this documentation package. This is a locally prepared private beta, not a hosted-service subscription, a city deployment agreement or a public release. No uptime commitment, support response time, indemnity, data-processing agreement or paid service is created by these documents. A separate signed agreement, if any, governs services it actually provides. -### Software license and rights +Software license and rights -Current Townlight-owned distributions identified in this candidate use **AGPL-3.0-only**. The full license is supplied with this documentation and with the source companion. The license governs rights to run, copy, modify and convey the covered software; these operational terms do not add restrictions to those rights. Historical grants and dependency licenses retain their own terms. CivicCast remains a separate product and is not relicensed by this documentation work. +Current Townlight-owned distributions identified in this candidate use AGPL-3.0-only. The full license is supplied with this documentation and with the source companion. The license governs rights to run, copy, modify and convey the covered software; these operational terms do not add restrictions to those rights. Historical grants and dependency licenses retain their own terms. CivicCast remains a separate product and is not relicensed by this documentation work. -When conveying covered software, retain applicable notices and provide the corresponding source and installation/build information required by the license. For a modified version supporting remote network interaction, follow section 13’s source-offer requirement. The companion archive identifies the source for this candidate; a link to a different public branch is not a substitute for the matching source. Read the supplied license for the complete conditions. See the [GNU license reference](https://www.gnu.org/licenses/agpl-3.0.html) and [GNU licensing FAQ](https://www.gnu.org/licenses/gpl-faq.en.html). +When conveying covered software, retain applicable notices and provide the corresponding source and installation/build information required by the license. For a modified version supporting remote network interaction, follow section 13’s source-offer requirement. The companion archive identifies the source for this candidate; a link to a different public branch is not a substitute for the matching source. Read the supplied license for the complete conditions. See the GNU license reference and GNU licensing FAQ. -### Data ownership and access +Data ownership and access Importing a document does not transfer its ownership or grant permission to publish it. The operating organization controls its accounts, access decisions, lawful source use, retention and review/release policy. Keep resident information, credentials, private notes and restricted evidence in their authorized locations. Documentation examples contain fictional data. No real city account, credential or record is required to exercise these examples in an isolated test environment. -### Local operation and external processors +Local operation and external processors The accepted beta workflow is local and uses named staff accounts. Station has separate storage and credentials. Configure backup destinations and optional model/network providers deliberately. A configured external provider may receive submitted prompts, images or audio according to that configuration and provider’s terms; this documentation does not promise that every optional configuration is offline. An email outbox or local public view does not establish external delivery or an internet deployment. This static documentation site has no analytics, account collection or remote font dependency. -### Staff decisions and source applicability +Staff decisions and source applicability Staff verify the jurisdiction, source currency, permissions, citations and proposed audience. Model output and generated guidance require review. No draft is automatically an official legal interpretation, zoning determination, permit approval, fee assessment, enforcement notice or records-release decision. Official permit fee authority remains with the adopted source and responsible organization; imported amounts do not become a new authoritative calculation. -### Beta operation and recovery +Beta operation and recovery Use the identified candidate in its supported fresh-install scope. Preserve backups and original evidence. Test physical equipment and chosen network/service configuration before relying on them. The supplied acceptance describes selected synthetic workflows, not every screen, vendor, field condition or upgrade. Operators decide whether a particular deployment meets their own operational obligations. -### Warranty and liability +Warranty and liability The covered software’s warranty and liability conditions are those in sections 15–17 of the supplied AGPL and any applicable separate written undertaking. This documentation creates no additional warranty or limitation beyond those terms. Third-party software is subject to its retained license notices. Nothing here removes rights that applicable law makes nonwaivable. -### Support and incident reporting +Support and incident reporting Use the project’s existing SUPPORT and SECURITY guidance for its matching repository. Report reproducible behavior with the version, operation and redacted logs. Do not put credentials, resident records or unredacted evidence in a public issue. Coordinate sensitive reports through the channel designated in SECURITY. No new support address or service commitment is invented here. -### Ending a beta exercise and document changes +Ending a beta exercise and document changes When an organization ends testing, it controls retention/export and removes access according to its policy. Uninstall may retain data; back up and inspect the selected removal options. Ending an exercise does not revoke rights already granted by AGPL. Later software/documentation versions must identify their changed candidate and scope; historical receipts retain their original identities. These terms do not claim that a city has accepted a contract merely by reading a manual. -## Glossary - -| Term | Meaning | -| --- | --- | -| Approval | An explicit authorized decision on the saved text/artifact. It is separate from saving or attachment. | -| Canonical record | The owning product’s retained identity and saved version, rather than an editable copied label. | -| Composition | The selected set of desktop modules; inspections-preview exposes the eight staff products. | -| Corresponding source | The source/build material matching the delivered covered program, subject to its license. | -| Derivative / Records copy | A separately prepared document with its own intended audience and hash. | -| Hash / SHA256 | A fingerprint of exact bytes. It detects change; it does not establish legal authority. | -| Idempotency | Repeating the same identified request has the same intended effect; changing its payload can be refused. | -| IPC | The native desktop command boundary between its browser interface and Rust host. | -| MCP | Model Context Protocol; no direct Townlight product server is enabled by this beta. | -| Original | Retained source bytes. A reviewed derivative does not replace them. | -| Provenance | Source, version, date, actor and relationship information retained with evidence. | -| Revision | An immutable saved version. Later edits do not inherit an earlier review automatically. | -| Snapshot | A fixed audience-specific copy tied to a source/reviewed revision. | -| Station | Townlight’s separate media boundary using a pinned CivicCast-derived engine; standalone CivicCast remains separate. | - - -## Alphabetical subject index - -- **Accounts and authentication** — [Security and permissions](#security-and-permissions). -- **AGPL and source** — [Terms of service and license](#terms-of-service-and-license). -- **API contracts** — [API and integration examples](#api-and-integration-examples). -- **Architecture** — [Architecture](#architecture). -- **Backup** — [Backup recovery and maintenance](#backup-recovery-and-maintenance). -- **Beta version** — [Beta identity](#beta-identity). -- **Configuration** — [Configuration and administration](#configuration-and-administration). -- **Evidence and acceptance** — [Verified workflows and limits](#verified-workflows-and-limits). -- **Fees and official decisions** — [Terms of service and license](#terms-of-service-and-license). -- **First run** — [First run](#first-run). -- **Handoffs and audience** — [Connected workflows](#connected-workflows). -- **MCP** — [MCP and automation boundary](#mcp-and-automation-boundary). -- **Originals and provenance** — [Security and permissions](#security-and-permissions). -- **Recovery** — [Backup recovery and maintenance](#backup-recovery-and-maintenance). -- **Staff procedures** — [Daily workflow](#daily-workflow). -- **Station configuration** — [Configuration and administration](#configuration-and-administration). -- **Technical stack** — [Technical specifications](#technical-specifications). -- **Troubleshooting** — [Troubleshooting](#troubleshooting). - -### Operating subject links - -- **Discretionary processes and staff review** — [Discretionary processes and staff review](#discretionary-processes-and-staff-review). -- **Explain the cited process** — [Explain the cited process](#explain-the-cited-process). -- **Keep parcel import and inspection in the right order** — [Keep parcel import and inspection in the right order](#keep-parcel-import-and-inspection-in-the-right-order). -- **Use the existing specialist review contracts** — [Use the existing specialist review contracts](#use-the-existing-specialist-review-contracts). - -## Source and document control +Glossary + + --------------------------------------------------------------------------------------------------------------------------------------------------------- + Term Meaning + ----------------------------------- --------------------------------------------------------------------------------------------------------------------- + Approval An explicit authorized decision on the saved text/artifact. It is separate from saving or attachment. + + Canonical record The owning product’s retained identity and saved version, rather than an editable copied label. + + Composition The selected set of desktop modules; inspections-preview exposes the eight staff products. + + Corresponding source The source/build material matching the delivered covered program, subject to its license. + + Derivative / Records copy A separately prepared document with its own intended audience and hash. + + Hash / SHA256 A fingerprint of exact bytes. It detects change; it does not establish legal authority. + + Idempotency Repeating the same identified request has the same intended effect; changing its payload can be refused. + + IPC The native desktop command boundary between its browser interface and Rust host. + + MCP Model Context Protocol; no direct Townlight product server is enabled by this beta. + + Original Retained source bytes. A reviewed derivative does not replace them. + + Provenance Source, version, date, actor and relationship information retained with evidence. + + Revision An immutable saved version. Later edits do not inherit an earlier review automatically. + + Snapshot A fixed audience-specific copy tied to a source/reviewed revision. + + Station Townlight’s separate media boundary using a pinned CivicCast-derived engine; standalone CivicCast remains separate. + --------------------------------------------------------------------------------------------------------------------------------------------------------- + +Alphabetical subject index + +- Accounts and authentication — Security and permissions. +- AGPL and source — Terms of service and license. +- API contracts — API and integration examples. +- Architecture — Architecture. +- Backup — Backup recovery and maintenance. +- Beta version — Beta identity. +- Configuration — Configuration and administration. +- Evidence and acceptance — Verified workflows and limits. +- Fees and official decisions — Terms of service and license. +- First run — First run. +- Handoffs and audience — Connected workflows. +- MCP — MCP and automation boundary. +- Originals and provenance — Security and permissions. +- Recovery — Backup recovery and maintenance. +- Staff procedures — Daily workflow. +- Station configuration — Configuration and administration. +- Technical stack — Technical specifications. +- Troubleshooting — Troubleshooting. + +Operating subject links + +- Discretionary processes and staff review — Discretionary processes and staff review. +- Explain the cited process — Explain the cited process. +- Keep parcel import and inspection in the right order — Keep parcel import and inspection in the right order. +- Use the existing specialist review contracts — Use the existing specialist review contracts. + +Source and document control This edition is authored from the immutable corresponding-source companion, the generated installed-domain schema and the retained workflow receipts. The current software versions and signed artifacts are unchanged. Public historical pages are not synchronized or published by this local documentation task. -### Workflow subject index - -- **Ask a parcel question** — [Daily workflow, step 4](#workflow-4). -- **Create a snapshot** — [Daily workflow, step 6](#workflow-6). -- **Import and inspect** — [Daily workflow, step 2](#workflow-2). -- **Prepare parcel data** — [Daily workflow, step 1](#workflow-1). -- **Record review and context** — [Daily workflow, step 5](#workflow-5). -- **Register cited rules** — [Daily workflow, step 3](#workflow-3). -- **Use it downstream** — [Daily workflow, step 7](#workflow-7). - -- [Source inventory and file hashes](docs/beta-1/reference/source-inventory.json) -- [All component metadata](docs/beta-1/reference/component-metadata.json) -- [Installed domain OpenAPI](docs/beta-1/reference/desktop-domain-openapi.json) -- [Workflow matrix](docs/beta-1/reference/workflow-matrix.json) -- [Full AGPL text](docs/beta-1/reference/AGPL-3.0.txt) +Workflow subject index + +- Ask a parcel question — Daily workflow, step 4. + +- Create a snapshot — Daily workflow, step 6. + +- Import and inspect — Daily workflow, step 2. + +- Prepare parcel data — Daily workflow, step 1. + +- Record review and context — Daily workflow, step 5. + +- Register cited rules — Daily workflow, step 3. + +- Use it downstream — Daily workflow, step 7. + +- Source inventory and file hashes + +- All component metadata + +- Installed domain OpenAPI + +- Workflow matrix + +- Full AGPL text diff --git a/apply_discretionary.py b/apply_discretionary.py index ebca158..dbedb68 100644 --- a/apply_discretionary.py +++ b/apply_discretionary.py @@ -7,16 +7,16 @@ from pathlib import Path HERE = Path(__file__).resolve().parent -PKG = HERE / 'civiczone' +PKG = HERE / 'townlight_zoning' # --- main.py: imports, route, page call ------------------------------------- target = PKG / 'main.py' text = target.read_text(encoding='utf-8') if 'discretionary_explanation' not in text: text = text.replace( - 'from civiczone.staff_context import classify_for_planner_review, get_staff_precedent', - 'from civiczone.discretionary import (Unavailable, explain, nonconformity_review_note)\n' - 'from civiczone.staff_context import classify_for_planner_review, get_staff_precedent') + 'from townlight_zoning.staff_context import classify_for_planner_review, get_staff_precedent', + 'from townlight_zoning.discretionary import (Unavailable, explain, nonconformity_review_note)\n' + 'from townlight_zoning.staff_context import classify_for_planner_review, get_staff_precedent') route = ''' @@ -27,7 +27,7 @@ class DiscretionaryExplanationRequest(BaseModel): observed: dict[str, str] = Field(default_factory=dict) -@app.post("/api/v1/civiczone/standards/process-explanation") +@app.post("/api/v1/townlight_zoning/standards/process-explanation") def discretionary_explanation(request: DiscretionaryExplanationRequest) -> dict[str, object]: """Explain the variance/CUP process a question is about, with citations. @@ -80,7 +80,7 @@ def lookup_dimensional_rule(*, zone_code: str, rule_type: str): return _Adapter() ''' - anchor = '\n\n@app.post("/api/v1/civiczone/questions/answer")' + anchor = '\n\n@app.post("/api/v1/townlight_zoning/questions/answer")' if anchor not in text: raise SystemExit('anchor not found') text = text.replace(anchor, route + anchor, 1) diff --git a/apply_public_panel.py b/apply_public_panel.py index bcb3909..e938b95 100644 --- a/apply_public_panel.py +++ b/apply_public_panel.py @@ -10,7 +10,7 @@ from pathlib import Path HERE = Path(__file__).resolve().parent -page = HERE / 'civiczone/public_ui.py' +page = HERE / 'townlight_zoning/public_ui.py' text = page.read_text(encoding='utf-8') marker = '