a bunch of stuff happened. I'll do better next commit...

docs/application-access.md

@@ -0,0 +1,25 @@
+# Application dashboard and assignments
+
+Sign in as an Administrator or configured System Administrator. Open **Application Access** in the user menu.
+
+On the first visit, use **Set up application directory**. This runs `migrations/001_application_access.sql` against the configured decauthy database, creating `applications` and `user_applications` and registering the two development URLs. It does not assign any user access. The migration is also available to run directly with your database tools. Repeating it preserves existing URLs and assignments.
+
+Choose a user and press **Load**. Select their applications and press **Save access**. Clearing all selections removes all of that user's assignments. Saving replaces the selection in one transaction and records the change in the journal. Disabled applications retain assignments but do not appear on the dashboard.
+
+After sign-in, customers see only their assigned active applications. The launch endpoint checks the assignment again before redirecting, so a removed assignment stops launches immediately.
+
+These links currently open the applications' existing sign-in flows. They do not convey authenticated identity or replace either application's access checks. The secure authentication handoff and legacy-user mappings are a subsequent integration step.
+
+For production, update `applications.application_url` to each product's HTTPS address. Each product keeps its own authentication and subscription permissions until integration is complete.
+
+Verification: test a user with zero, one, and two assignments; clear an assignment and confirm the corresponding launch is denied; confirm a regular user cannot open or post to the administration routes. Administrator account-management routes are also protected server-side because changing an account's role would otherwise bypass assignment administration.
+
+## Existing application accounts
+
+Use **Enable account links** on the Application Access page to create the account-link table without changing existing assignments. Fresh directory setup now creates this table too.
+
+After loading a DEC user, enter the existing `user_serial` from each destination application's `users` table. Matching usernames can help an administrator locate the record, but do not constitute automatic identity verification. Confirm the record belongs to the same customer before saving. Different usernames and different numeric IDs between applications are supported.
+
+A destination account can be linked to only one DEC user. Duplicate links return a conflict and roll back the entire save, including assignment changes. Blank fields remove mappings. Unchecking application access preserves its account mapping, so restoring access can retain the same customer history. Account existence and active status must also be checked by the destination during the eventual authentication handoff.
+
+This step prepares the identity mapping only. There is no cross-application authentication token or handoff enabled yet, and destination passwords continue to work as before.

docs/shared-sign-in-deployment.md

@@ -0,0 +1,53 @@
+# Shared sign-in deployment
+
+## Confirmed production addresses
+
+| Service | Address |
+| --- | --- |
+| DEC sign-in portal | https://login.realestatedatainc.com/ |
+| Real Estate Data Inc | https://apps.realestatedatainc.com/realestatedatainc/ |
+| Georgia Housing Report | https://apps.realestatedatainc.com/atlhousingreport/ |
+
+## Confirmed staging addresses
+
+| Service | Address |
+| --- | --- |
+| DEC sign-in portal | https://staging.realestatedatainc.com/decauthy/ |
+| Real Estate Data Inc | https://staging.realestatedatainc.com/realestatedatainc/ |
+| Georgia Housing Report | https://staging.realestatedatainc.com/atlhousingreport/ |
+
+The current development environment uses HTTP. Shared sign-in will be verified on these separate HTTPS staging copies. Staging clients, signing keys, sessions, and databases must be separate from production. Use test users and direct staging mail to a test inbox.
+
+After initializing the staging application directory, run `deployment/staging-application-urls.sql` against the staging decauthy database to set its dashboard destinations. This script is intentionally excluded from automatic directory setup.
+
+## Staging preparation
+
+1. Create HTTPS staging sites for all three applications with certificates trusted by the test browser and server. Keep each application's current login available during integration.
+2. Create separate staging databases. Configure each copy to use its staging database and test mail destination before opening it to testers.
+3. Deploy decauthy's dashboard and account-link changes. Initialize its application directory, replace the development application URLs with the actual staging URLs, and assign one test user to each product.
+4. Link that test user to its existing local user_serial in each staging product. Confirm the destination user is active and has the intended test subscriptions.
+5. Install and configure the identity provider on staging, then register one client for each destination application. Exact callback URLs will be chosen when the callback handlers are implemented. Do not register guessed or wildcard callbacks.
+
+## Proposed PHP identity provider
+
+SimpleSAMLphp with its OpenID Connect provider module is a self-hosted PHP option. The currently documented SimpleSAMLphp baseline is PHP 8.3 or newer; Composer must resolve the selected release and extensions on the actual PHP 8.5 server before compatibility is considered verified.
+
+Install SimpleSAMLphp separately from the decauthy application, following the official installation guide. Publish only its public directory; configuration and private signing keys remain outside the web root. From that installation's directory, install the OIDC module with:
+
+```sh
+composer require simplesamlphp/simplesamlphp-module-oidc
+composer check-platform-reqs
+```
+
+The provider needs an authentication integration with decauthy's central accounts, its own protocol storage, signing keys, and exact client registrations. Installing the module alone does not connect decauthy's current login session to the provider. Neither that integration nor the destination callbacks have been implemented yet.
+
+Sources:
+- https://simplesamlphp.org/docs/stable/simplesamlphp-install.html
+- https://simplesamlphp.org/docs/contrib_modules/oidc/2-oidc-installation.html
+- https://simplesamlphp.org/docs/contrib_modules/oidc/3-oidc-configuration.html
+
+## Acceptance checks before production
+
+Verify central login opens each assigned product as the mapped existing user, preserving its local permissions and history. Test missing mappings, inactive destination users, denied assignments, expired or reused authorization codes, incorrect state/nonce, and incorrect client or callback. Decide and verify how product sign-out, DEC sign-out, and removal of access affect existing sessions.
+
+After staging passes, register production clients with separate secrets and signing keys and configure the confirmed production URLs. `deployment/production-application-urls.sql` updates dashboard destinations only and is intentionally excluded from the automatic directory setup. No production database changes or deployments have been performed from this chat.