auth: publish self-hosted administration foundations

docs/ORGANIZATIONS.md

@@ -8,10 +8,19 @@ environments; environments own application services. Teams are optional groups
 of active organization members.
 
 `organizations.Service` creates those resources and issues digest-backed,
-expiring, single-use invitations. Acceptance verifies that the authenticated
-user's normalized email matches the invitation before activating membership.
-Applications own invitation pages, email or out-of-band delivery, organization
-deletion policy, and account recovery.
+expiring, single-use invitations. An invitation may carry one direct role and
+up to sixteen reviewed team memberships. Acceptance verifies that the
+authenticated user's normalized email matches and applies the membership,
+role, teams, consumption marker, and audit event in one transaction.
+Applications own invitation pages, email or out-of-band delivery, active-source
+checks before archival, and account recovery.
+
+Organizations and teams use optimistic revisions and reversible
+`active`/`archived` states. Archived objects keep their history but contribute
+no effective authority. Memberships may be suspended, reactivated, or removed;
+team membership can be removed independently. Configure `OwnerRole` when
+constructing the service before exposing membership-removal operations. The
+SQLite adapter then refuses to suspend or remove the final active direct owner.
 
 `access.Service` evaluates a permission against a complete resource scope:
 
@@ -34,8 +43,8 @@ grant organization-data access. If an operator must inspect tenant data during
 an incident, use a reasoned break-glass grant. It expires within one hour and
 creates an append-only audit event in the same transaction.
 
-The SQLite adapter namespaces all tables, enforces organization membership and
-resource ancestry before accepting a binding, and keeps invitations and
-sessions as digests. Applications remain responsible for database backup,
-filesystem ownership, retention, and presenting audit history to organization
-owners.
+The SQLite adapter namespaces all tables, enforces active organization and team
+membership plus resource ancestry before accepting or evaluating a binding,
+and keeps invitations and sessions as digests. Applications remain responsible
+for database backup, filesystem ownership, retention, and presenting audit
+history to organization owners.

docs/PASSKEYS.md

@@ -37,6 +37,14 @@ timestamp, UUID, or counter for the random challenge.
 5. Sensitive operations call `BeginApproval` with a canonical application
    payload and `FinishApproval` with those exact same bytes. Any drift fails.
 
+For an existing password-backed account, call `BeginPasswordMigration` only
+from an authenticated account session and finish with
+`FinishPasswordMigration`. The registration ceremony is bound to that user.
+Successful completion stores the passkey, removes the password credential,
+clears the password-change flag, revokes every session and pending ceremony,
+and appends the audit event atomically. The application must clear the current
+session cookie and return the user to passkey login after success.
+
 `authhttp.WritePasskeyBegin` and `authhttp.ReadPasskeyFinish` provide bounded
 JSON framing only. They do not register routes, authorize requests, serve
 JavaScript, or set sessions automatically.