朱子纯 / vibe-erp

docs: align deeper how-to docs with current code state

The previous docs commit fixed README + CLAUDE + the three "scope note"
guides but explicitly left the deeper how-to docs as-is, claiming the
architecture hadn't changed. That was wrong on closer reading: those
docs still described the pre-single-tenant world (tenant_id columns,
two-wall isolation, per-tenant routing) and the pre-implementation
plug-in API (class-based @PluginEndpoint controllers, ResponseBuilder,
context.log instead of context.logger, plugin.yml entryClass field).
A reader following any of those guides would write code that doesn't
compile.

This commit aligns them with what the framework actually does today.

What changed:

* docs/architecture/overview.md
  - Guardrail #5 rewritten from "Multi-tenant in spirit from day one"
    to "Single-tenant per instance, isolated database" matching
    CLAUDE.md.
  - The api.v1 package layout updated to match the actual current
    surface: dropped `Tenant`, added `PrincipalId`,
    `PersistenceExceptions`, the full plug-in package
    (PluginContext, PluginEndpointRegistrar, PluginRequest/Response,
    PluginJdbc, PluginRow), and the two live cross-PBC facades
    (IdentityApi, CatalogApi).
  - The whole "Multi-tenancy" section replaced with
    "Single-tenant per instance" — drops the two-wall framing,
    drops per-region routing, drops tenant_id columns and RLS.
    The single-tenant rationale is explained in line with the
    rest of the framework.
  - Custom fields and metadata store sections drop "per tenant"
    and tenant_id from their column lists.
  - Audit row in the cross-cutting table drops tenant_id from
    the column list and adds the PrincipalContext bridge note
    that's actually live as of P4.1.
  - "Tier 1 — Key user, no-code" intro drops "scoped to their tenant".

* docs/plugin-api/overview.md
  - api.v1 package layout updated to match the real current surface
    (same set of additions and deletions as the architecture
    overview).
  - Per-package orientation table rewritten to describe what is
    actually in each package today, including which parts are
    live (event/, plugin/, http/) and which are stubbed (i18n/,
    workflow/, form/) with the relevant implementation-plan unit
    referenced.

* docs/plugin-author/getting-started.md — full rewrite. The previous
  version walked an author through APIs that don't exist:
    • `Plugin.start(context: PluginContext)` and
      `Plugin.stop(context: PluginContext)` — actual API is
      `start(context)` and `stop()` (no arg), with the Pf4jPlugin +
      VibeErpPlugin dual-supertype trick using import aliases.
    • `context.log` — actual is `context.logger` (PluginLogger
      interface).
    • `plugin.yml` with `entryClass:` field and a structured
      `metadata.i18n:` subkey — actual schema has no entryClass
      (PF4J reads `Plugin-Class` from MANIFEST.MF) and `metadata:`
      is a flat list of paths.
    • Class-based `@PluginEndpoint` controllers with `ResponseBuilder`
      — actual is lambda-based registration via
      `context.endpoints.register(method, path, handler)` returning
      `PluginResponse`.
    • `request.translator.format(...)` — translator currently
      throws UnsupportedOperationException; the example would crash.

  The new version walks through:
    1. The compileOnly api.v1 + pf4j dependency setup.
    2. The dual-supertype Pf4jPlugin + VibeErpPlugin trick with
       import aliases (matches the actual reference plug-in).
    3. The real JAR layout (META-INF/MANIFEST.MF for PF4J,
       plugin.yml for human metadata, META-INF/vibe-erp/db/changelog.xml
       for Liquibase, META-INF/vibe-erp/metadata/<id>.yml for the
       metadata loader).
    4. Liquibase changelog at the unique META-INF path (not the
       host's `db/changelog/master.xml` path which would collide
       on parent-first classloader lookup — the bug we hit and
       fixed in commit 1ead32d7).
    5. Lambda-based endpoint registration with real working
       examples (path templates, queryForObject, update, JSON
       body parsing).
    6. Metadata YAML shape matching what MetadataLoader actually
       parses.
    7. The boot-log sequence the operator will see, taken from
       a real smoke run.
    8. An honest "what this guide does not yet cover" list with
       implementation-plan unit references.

* docs/i18n/guide.md
  - Added a "Status" callout at the top: the api.v1 contract is
    locked, the ICU4J implementation is P1.6 and not yet wired,
    `context.translator` currently throws.
  - Bundle filename convention corrected from `<locale>.properties`
    to `messages_<locale>.properties` (matches what the reference
    plug-in actually ships).
  - plugin.yml example updated to show the flat `metadata:` array
    that PluginManifest actually parses (the previous structured
    `metadata.i18n:` subkey doesn't exist in the schema).
  - Merge precedence renamed "tenant overrides" → "operator
    overrides" since vibe_erp is single-tenant per instance.
  - LocaleProvider resolution chain updated to drop "tenant default"
    and reference `vibeerp.i18n.default-locale` configuration.
  - "Time zones are per-tenant" → "per-user with an instance default".
  - Locale-add reference to "i18n-overrides volume" annotated as
    "once P1.6 lands".

* docs/customer-onboarding/guide.md
  - Section 3 "Create a tenant" deleted; replaced with
    "Configure the instance" pointing at vibeerp.instance.* config.
  - First-boot bullet list rewritten to drop the bogus
    "create default tenant row in identity__tenant" step (no such
    table) and add the real metadata-loader and per-plug-in lifecycle
    steps that happen.
  - Mounted-volume table updated: `i18n-overrides/` is "operator
    translation overrides", not "tenant-level".
  - "Bind users to roles, bind roles to tenants" simplified;
    OIDC group claims annotated as P4.2 (not yet wired).
  - Go-live checklist drops "non-production tenant" wording and
    "tenant locale defaults" (now instance-level config).
  - "Hosted multi-tenant operations" deferred-list item rewritten
    to "hosted operations: provisioning many independent vibe_erp
    instances", matching the new single-tenant deployment model.

* docs/form-authoring/guide.md
  - Tier 1 section drops "scoped to the tenant",
    "tweaking for a specific tenant", "tenant-specific custom field".

* docs/workflow-authoring/guide.md
  - "Approval chains that vary per tenant" → "Approval chains the
    customer wants to author themselves".

* docs/index.md
  - Architecture overview row description updated from
    "multi-tenancy" to "single-tenant deployment model".
  - i18n guide row description updated from "tenant overrides"
    to "operator overrides".

Build: ./gradlew build still green (no source touched).

The remaining `tenant` references in docs are now ALL intentional —
they appear in sentences like "vibe_erp is single-tenant per instance",
"there is no create-a-tenant step", "no per-tenant bundles". The
historical specs under docs/superpowers/specs/ were intentionally
NOT touched: those are dated design records, and the implementation
plan already had the single-tenant refactor noted at the top.