arcane-os 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.20.0
+
+- Restore repository-shaped application packages: selected app files remain
+  under `apps/<id>/`, alongside shared `arcane/` and configured runtime routes.
+  Authored document bases, import maps, module-relative imports and application
+  resource paths retain their development layout without rewriting product
+  documents or application code to relocate them.
+- Restore deployment-relative `ARCANE_APP_RELEASE.app.start` and a root
+  `index.html` launcher while preserving the app-relative `app.entry` identity.
+  Package consumers use `app.start` for navigation. SDK packaged previews honor
+  that field and retain support for earlier flat packages through `app.entry`.
+- Keep generated PWA files at the deployment root, resolve manifest metadata
+  against the packaged app directory, and preserve app-relative offline
+  selections alongside shared runtime paths. Source import-map inspection keeps
+  app-relative document paths and separately reports emitted package paths.
+- Align packaging references with the current public return values and explicit
+  source import-map generation. Add package-layout and nested-deployment test
+  source while retaining complete authored-content coverage.
+
+## 0.19.0
+
+- Read mail credentials from `.env.json` in the invocation directory through
+  portable Node file APIs. Remove the Windows Credential Manager subprocess,
+  embedded PowerShell/C# helper, helper timeouts, and transport-only machinery.
+  Existing Windows credential records remain untouched; populate the JSON file
+  explicitly when adopting this configuration change.
+- Default mail commands to the top-level `RESEND_API_KEY`; `--profile mail`
+  selects that same key. Preserve named key set/status/delete operations through
+  exact `MAIL_PROFILES` entries, retaining unrelated JSON settings and naming
+  the missing setting and file before send or server startup.
+- Ignore `.env.json` in the SDK checkout and newly scaffolded workspaces. Update
+  the mail reference and purpose-gate report with the portable configuration
+  contract and the reasons for each retained or removed operation.
+
 ## 0.18.0
 
 - Adopt published `node-http-server` 10.0.0. PEM-backed development and

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.18.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.20.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/docs/architecture.md

@@ -199,9 +199,27 @@ URLs and release schema:
 apps/<id>/arcane-app.json
 apps/<id>/arcane-package.json
 apps/<id>/index.html
+dist/<id>/index.html
+dist/<id>/apps/<id>/index.html
 dist/<id>/ARCANE_APP_RELEASE.json
 ```
 
+Packaging places each selected app file beneath `apps/<id>/` in the release
+and preserves every shared route destination. When no selected shared payload
+supplies a root `index.html`, the SDK generates one that opens the selected app
+entry. Authored document bases, app URLs, relative module imports, and shared
+runtime paths therefore resolve through the same layout in
+source development and packaged delivery. Packaging consumes the saved source
+and managed import maps; use `arcane import-map` to refresh those maps, or the
+ordinary `arcane dev` startup that performs that refresh.
+
+The release manifest keeps `app.entry` relative to the app directory and records
+the package launch URL in `app.start`, such as
+`./apps/hello-world/index.html`. Its complete `files` inventory includes the
+root `index.html` and the prefixed app files. Packaged browser serving opens
+`app.start`; a previously generated flat release without `app.start` retains
+its `app.entry` launch path.
+
 The authored schema-2 descriptor is canonical for new apps and projects an
 exact schema-1 `arcane-package.json` for current consumers. Existing Arcane
 apps synthesize that descriptor from their schema-1 package plus the current

package/docs/reference/cli.md

@@ -32,7 +32,7 @@ and exits nonzero on failure. Machine output is defined by
 | `arcane update-check` | Performs one explicit, read-only npm dist-tag query for the installed SDK version. |
 | `arcane targets` | Lists target ids, declared status, formats, architectures, signing profiles, methods, and pairing reason. |
 | `arcane repo status\|pull\|push` | Runs one selected repository operation for the current app workspace. |
-| `arcane mail key set\|status\|delete` | Manages one server-only Resend API-key profile in Windows Credential Manager. |
+| `arcane mail key set\|status\|delete` | Manages one server-only Resend API-key profile in `.env.json`. |
 | `arcane mail send` | Performs one explicit, idempotency-keyed Resend attempt from a complete JSON report on redirected stdin. |
 | `arcane mail serve` | Starts one Arcane-to-Resend gateway with a server-only provider profile, a selected listener, and optional CORS and recipient configuration. |
 
@@ -195,8 +195,8 @@ Wrong or duplicate explicit app identity fails. The renderer then requires one
 path-correct base for every selected document. Included HTML files with neither
 the identity marker nor an active base are component fragments: they remain
 package files and are not rewritten with a document-level import map.
-Packaging and development use the same discovery owner, so directly navigable
-source pages and packaged pages receive the same complete managed import-map JSON.
+Packaging and development use the same discovery owner. Packaging consumes
+the saved managed import maps in directly navigable source pages.
 
 ```text
 arcane import-map [--workspace <directory>] [--app <id>]
@@ -254,19 +254,12 @@ together. A post-commit observer failure preserves delivery with
 `eventDelivery.status === 'degraded'` and `ARCANE_EVENT_DELIVERY_FAILED`; it
 does not roll back complete application content.
 
-An external package also publishes `/ARCANE_RUNTIME_PROJECTION.json`. The JSON
-is `{schemaVersion:1,kind:'arcane-app-runtime-projection',sdkVersion,
-pathPrefix:'arcane/',files:[{path}]}` and lists the complete packaged runtime.
-The development server exposes the same public route from its workspace
-projection. The private `/ARCANE_APP_RELEASE.json` record is not served to
-application code. Malformed projection data fails
-`ARCANE_RUNTIME_PROJECTION_INVALID`.
-
 `new` and `init` generate the map during scaffolding. `dev` refreshes all
-selected documents once before binding; non-dry-run `package` refreshes them
-once, then collects the complete release. Packaging does not run tests or
-checks automatically. Browser `build` and paired native packaging reuse the
-package flow. Explicit `test` and `check` operations read the existing map without regenerating it;
+selected documents once before binding. `package` consumes the saved source
+and maps; use `import-map` to refresh them explicitly before selecting output
+that needs updated maps. Packaging does not run tests or checks automatically.
+Browser `build` and paired native packaging reuse the package flow.
+Explicit `test` and `check` operations read the existing map without regenerating it;
 `verify`, `bundle`, and browser `run` do not regenerate it. There is no
 watcher, polling, scheduled refresh, download, or self-update behavior.
 
@@ -504,9 +497,12 @@ npm exec -- arcane check --app hello-world
 ### Overview
 
 Creates one complete browser release beneath `dist/<id>/`, preserving the prior
-output until the replacement is complete. It refreshes the selected document
-map once, then assembles `dist`. Packaging does not run tests or checks
-automatically.
+output until the replacement is complete. It consumes saved source and managed
+import maps, places app files beneath `apps/<id>/`, and retains the configured
+shared route destinations. When selected shared content supplies no root
+`index.html`, the SDK generates one that opens the selected app entry.
+Source document bases and resource URLs therefore retain their development
+layout. Packaging does not run tests or checks automatically.
 
 ```text
 arcane package [--app <id>] [--dry-run]
@@ -515,6 +511,9 @@ arcane package [--app <id>] [--dry-run]
 ### Result
 
 The result includes the release root, manifest, and complete selected inventory.
+`ARCANE_APP_RELEASE.json` keeps the authored app-relative `app.entry` and records
+the package launch URL in `app.start`, such as `./apps/hello-world/index.html`.
+The file inventory includes that app tree and the root `index.html`.
 `--dry-run` plans the package without refreshing source, running tests, or
 replacing output.
 
@@ -672,6 +671,8 @@ npm exec -- arcane build \
 
 For `--target browser`, starts the existing current `dist/<app>` release; it
 does not package, rebuild, test, check, or verify that release automatically.
+It opens the release manifest's `app.start` URL. Older flat releases without
+that field continue to open their `app.entry` path.
 The preview always uses HTTPS with the workspace certificate pair. Supply
 `--cert <file> --key <file>` together to use another pair; see
 [development HTTPS setup](#development-https-setup).
@@ -813,22 +814,47 @@ npm exec -- arcane repo status
 
 ### Resend credential profiles
 
-The credential subcommands select one local profile:
+The mail commands read `.env.json` from the invocation directory on Windows,
+Linux, and macOS. The credential subcommands select one profile in that file:
 
 ```text
-arcane mail key set <profile> [--secret-stdin]
-arcane mail key status <profile>
-arcane mail key delete <profile>
+arcane mail key set [profile] [--secret-stdin]
+arcane mail key status [profile]
+arcane mail key delete [profile]
 ```
 
 `key set` reads the Resend API key from a hidden terminal prompt. The
 `--secret-stdin` form is for deliberately redirected non-interactive input and
-rejects a TTY before reading. The key is sent to the Windows Credential Manager
-helper over child-process stdin, never argv, and no plaintext fallback is
-created. Status reports only whether the profile exists. Delete returns the
-selected profile with `exists:false`; it intentionally does not distinguish a
-new deletion from an already-absent profile. Non-Windows hosts report the
-credential operation as unavailable.
+rejects a TTY before reading. The key is written to `.env.json` and is never
+accepted in argv or returned in status output. The optional profile defaults
+to `mail`, which selects top-level `RESEND_API_KEY`. Any other exact profile
+selects `MAIL_PROFILES[profile].RESEND_API_KEY`, with no default-key fallback.
+
+The minimal file is:
+
+```json
+{
+  "RESEND_API_KEY": ""
+}
+```
+
+Fill in the key before starting mail, and add `.env.json` to the project's
+`.gitignore`; the SDK repository already ignores it. Set and delete preserve
+the file's other settings and profiles. Status returns the selected profile,
+`provider:'resend'`, `storage:'.env.json'`, and `exists`. Delete returns
+`exists:false` for both a removed and an already-absent credential.
+
+Programmatic `createToolchain().mail(...)` resolves the configuration directory
+from `cwd ?? workspaceRoot ?? process.cwd()`. This uses ordinary Node file
+access rather than platform-specific credential processes. An Android host
+supplies a compatible Node runtime and an accessible configuration directory.
+Existing Windows Credential Manager records remain untouched; the JSON reader
+does not migrate or fall back to them. Mail reads JSON directly and does not
+populate or depend on process environment variables for this key.
+
+Missing files or missing/empty selected keys stop `send` and `serve` with the
+configuration path and exact JSON setting to fill in. Invalid JSON and file
+access failures remain observable without printing credential content.
 
 Machine output for `key set` requires `--secret-stdin`. Raw CLI arguments are
 not included in acceptance events, and usage errors do not echo unknown option
@@ -840,7 +866,7 @@ or positional values.
 server:
 
 ```text
-arcane mail send --profile <profile> [--from <verified-sender>] --report-key <id> --report-stdin [--request-timeout <ms>]
+arcane mail send [--profile <profile>] [--from <verified-sender>] --report-key <id> --report-stdin [--request-timeout <ms>]
 ```
 
 `--report-stdin` is mandatory and rejects a terminal before attaching input
@@ -861,8 +887,8 @@ Resend owns their accepted shape. The adapter removes the application-only
 `type` field and applies `--from` when supplied; otherwise the report or provider
 template supplies the sender. Direct CLI sending has
 no configured fallback recipients. The Resend credential comes only from the
-selected Windows Credential Manager profile; neither it nor report content is
-accepted through argv or environment variables.
+selected `.env.json` profile; omitting `--profile` selects `mail`. Neither the
+key nor report content is accepted through argv or process environment variables.
 
 The caller owns the nonempty `--report-key`, which is forwarded unchanged.
 Reuse the same key only with the same
@@ -883,10 +909,11 @@ loss after the attempt begins is ambiguous because Resend may have accepted it.
 `mail serve` starts one owned Node HTTP gateway:
 
 ```text
-arcane mail serve --profile <profile> [--from <verified-sender>] [--app <label>] [--origin <exact-origin>] [--allow-to <addresses>] [--host 0.0.0.0] [--port 8025] [--request-timeout <ms>]
+arcane mail serve [--profile <profile>] [--from <verified-sender>] [--app <label>] [--origin <exact-origin>] [--allow-to <addresses>] [--host 0.0.0.0] [--port 8025] [--request-timeout <ms>]
 ```
 
-The selected credential profile supplies only the server-side Resend API key.
+The selected `.env.json` profile supplies only the server-side Resend API key;
+omitting `--profile` selects `mail`.
 The CLI does not read a browser app key. Its optional `--app` value labels the
 server; the incoming request's `X-Mail-App` identifies the application for
 subscription verification. The HTTP authentication contract pairs that

package/docs/reference/mail.md

@@ -13,12 +13,14 @@ gateway and is never included in browser or WebAssembly state.
 | `MailTransport.mjs` | Browser, WebView, or compatible Fetch host | Sends one already-persisted request to the configured Arcane gateway with the stable report key as its idempotency key. |
 | `arcane mail send` | Node on the local machine | Reads one complete provider-neutral report from redirected stdin and performs one explicit Resend attempt with a caller-owned idempotency key. |
 | `arcane mail serve` | Node on the configured host | Owns caller verification, protects the provider credential, applies explicitly configured recipient and origin settings, and makes one server-side Resend request. |
-| `arcane mail key ...` | Node on Windows | Stores, inspects, or deletes a Resend API key in Windows Credential Manager. |
+| `arcane mail key ...` | Node on Windows, Linux, or macOS | Stores, inspects, or deletes a Resend API key in the selected `.env.json`. |
 
 The browser never receives the Resend API key. The gateway never writes that
 key to source, argv, logs, events, fixtures, browser storage, or its public
-lifecycle result. Non-Windows hosts report credential operations as unavailable;
-there is no plaintext fallback.
+lifecycle result. The CLI and gateway use the same Node filesystem and network
+interfaces on Windows, Linux, and macOS. An Android host supplies a compatible
+Node runtime and an accessible configuration directory; the mail implementation
+contains no Windows credential process or platform-specific path convention.
 
 ## Public npm import
 
@@ -42,8 +44,8 @@ import Mail,{
   and `sendMailReport`.
 
 This entrypoint contains only the portable browser/WebView runtime, outbox, and
-transport contract. It does not import the Node HTTP gateway or Windows
-Credential Manager adapter. Programmatic developer tooling reaches those
+transport contract. It does not import the Node HTTP gateway or its filesystem
+credential adapter. Programmatic developer tooling reaches those
 host-owned operations through the existing `createToolchain().mail(...)`
 boundary; ordinary operators use `arcane mail send`, `arcane mail serve`, and
 `arcane mail key ...`. This keeps Node credential and server authority out of a
@@ -53,9 +55,9 @@ browser import while preserving one shared CLI/toolchain implementation.
 
 Arcane Mail deliberately separates two credentials:
 
-- The **Resend API key** is provider authority. `arcane mail key set <profile>`
-  stores it in Windows Credential Manager. `mail send --profile <profile>` and
-  `mail serve --profile <profile>` read it only inside the owning Node process.
+- The **Resend API key** is provider authority. The Node process reads it from
+  `.env.json`. `arcane mail key set [profile]` can store it there through hidden
+  input; `mail send` and `mail serve` read the selected profile inside that process.
 - The **subscription key** is the application user's subscription credential.
   When present, the browser sends it as `Authorization: Bearer <subscriptionKey>`,
   with the exact application name in `X-Mail-App`. The application name identifies the
@@ -270,21 +272,69 @@ committed acceptance result.
 
 ## Operate the CLI and gateway
 
-Store one Resend key under a local profile:
+Create `.env.json` in the directory from which the mail command runs, then fill
+in the provider key:
+
+```json
+{
+  "RESEND_API_KEY": ""
+}
+```
+
+The SDK repository ignores `.env.json`. Keep the same entry in a consuming
+project's `.gitignore`. This is a JSON configuration file; the mail commands
+read it directly without copying its contents into `process.env`.
+
+The default profile is `mail`, which selects top-level `RESEND_API_KEY`.
+The explicit `--profile mail` form selects the same setting. Other profile names
+select exact entries under `MAIL_PROFILES`:
+
+```json
+{
+  "RESEND_API_KEY": "",
+  "MAIL_PROFILES": {
+    "another-provider-account": {
+      "RESEND_API_KEY": ""
+    }
+  }
+}
+```
+
+An absent named profile does not fall back to the default key. The profile
+selects Resend provider credentials; it is separate from the incoming
+application name and subscriber key.
+
+Programmatic operations resolve `.env.json` from `options.cwd`, then
+`options.workspaceRoot`, then `process.cwd()`, choosing the first supplied
+directory. The CLI uses its invocation directory. There is no upward directory
+search or dependency on a Windows installation directory or temporary-directory
+environment variable.
+
+The existing key commands manage the same file:
 
 ```text
-arcane mail key set arcane-dev
-arcane mail key status arcane-dev
-arcane mail key delete arcane-dev
+arcane mail key set
+arcane mail key status
+arcane mail key delete
 ```
 
 `key set` prompts with hidden input. `--secret-stdin` is the explicit
-non-interactive alternative and rejects a TTY.
+non-interactive alternative and rejects a TTY. Each command accepts an optional
+profile argument, defaulting to `mail`. Set and delete preserve other JSON
+settings and profiles; status reports existence without returning the key.
+Results identify `storage: '.env.json'`. An already-absent deletion succeeds
+with `exists: false`.
+
+Existing Windows Credential Manager records remain untouched. The JSON path
+does not read, migrate, or delete those records; populate the selected JSON
+setting to use it. Missing files or missing/empty provider settings produce an
+actionable startup/send error naming the file and exact setting. Unreadable or
+invalid JSON is reported without including credential content in the error.
 
 Perform one provider attempt directly from the SDK CLI:
 
 ```text
-arcane mail send --profile arcane-dev --from "Arcane <verified@example.com>" --report-key <stable-id> --report-stdin
+arcane mail send --from "Arcane <verified@example.com>" --report-key <stable-id> --report-stdin
 ```
 
 The redirected UTF-8 JSON object is read completely. Its fields and values
@@ -312,7 +362,7 @@ deadline.
 Start the gateway:
 
 ```text
-arcane mail serve --profile arcane-dev --from "Arcane <verified@example.com>"
+npm exec -- arcane mail serve --profile mail --host 0.0.0.0 --port 8025
 ```
 
 The default listener is `0.0.0.0:8025`; `--host` and `--port` select its bind

package/docs/reference/pwa.md

@@ -39,13 +39,20 @@ display preference, routes and descriptions. Use real app icons; the SDK does
 not invent branding or claim that a browser has installed the app.
 
 Manifest URL fields are relative to the application directory. Source delivery
-and packaged delivery resolve those fields into their respective layouts.
-Absolute URL fields retain their authored destination.
+and packaged delivery retain the app tree at `apps/<id>/`. For packaged output,
+the default `start_url` is `./apps/<id>/<entry>`, resolved from the generated
+root manifest. The default `id` and `scope` remain `./`, preserving the existing
+deployment-root installation identity. Authored relative URL fields, including
+explicit `id` and `scope` values, resolve against `./apps/<id>/`; an icon such
+as `img/library.png` therefore remains beneath the app directory. Absolute URL
+fields retain their authored destination.
 
 `offline.include` and `offline.exclude` select literal paths or directory
 prefixes from the selected emitted inventory. An omitted or empty include list
 selects that inventory; exclusions subtract from it. App files use app-relative
 paths and shared runtime files use paths such as `arcane/sdk/pwa.mjs`.
+For example, selecting `modules` matches packaged
+`apps/<id>/modules/...`; emitted offline URLs keep the `apps/<id>/` prefix.
 The application entry and generated PWA shell records are retained. Select the
 resources needed by every offline page, including its shared modules and styles.
 The worker script itself is never an application cache entry.
@@ -67,6 +74,13 @@ Browser packaging emits these files at the selected deployment root:
 | `arcane-sw.js` | Stable worker URL with the selected offline manifest embedded in its source. |
 | `arcane-pwa.mjs` | Independent registration and installation-component bootstrap importing the SDK client. |
 
+The selected app files remain under `apps/<id>/`, with shared runtime routes
+alongside them. The SDK supplies a root `index.html` launcher when selected
+shared content has no root page. The generated PWA files stay at the deployment
+root so their worker can serve the selected app and shared resources. The
+worker is registered for the deployment root independently of any app-authored
+manifest scope.
+
 Each packaged output gets one deployment revision shared by its offline
 manifest and worker. It distinguishes separately generated outputs even when
 their app and SDK versions match. It is not a content measurement.

package/docs/reference/sdk-api.md

@@ -719,6 +719,12 @@ matching `meta[name="arcane-app-id"]`; unmarked pages with an active `base`
 remain selected for patch compatibility. Included HTML with neither signal is
 retained as a package fragment rather than rewritten as a document.
 
+`entry` and each app browser document's `path` stay relative to the app
+directory. Each browser document also reports `packagePath`, the emitted path
+such as `apps/hello-world/index.html`. The complete `files` inventory uses
+package-relative paths and includes the root `index.html`. Shared
+files retain their configured route destinations.
+
 ### Availability and normalization
 
 **Node.** Normalized SDK validation with complete canonical archive and release content. Deep protocol: [SDK packager and deterministic bundle contract](protocols.md).
@@ -772,27 +778,22 @@ when explicitly requested or when required for this selected release output.
 async packageApp(options)
 ```
 
-Import it from `arcane-os` or `arcane-os/packager`. Packaging refreshes the
-managed map once and preserves the complete selected source and browser
-document inventory. It rejects malformed configuration, descriptors,
-and the malformed selected release archive while preserving the previously
-selected output on failure. Each selected browser document receives the same
-deterministic map. The package root also contains the public
-`ARCANE_RUNTIME_PROJECTION.json` inventory:
-
-```javascript
-{
-  schemaVersion: 1,
-  kind: 'arcane-app-runtime-projection',
-  sdkVersion: '0.5.18',
-  pathPrefix: 'arcane/',
-  files: [{path}]
-}
-```
+Import it from `arcane-os` or `arcane-os/packager`. Packaging consumes the saved
+source and managed import maps. Refresh maps through `arcane import-map` or
+ordinary `arcane dev` startup before selecting output that needs updated maps.
+The package preserves the complete selected content, applying the documented
+asset-version and enabled browser-PWA transformations to resource references.
+Malformed configuration or descriptors fail while preserving the prior output.
 
-The projection is an inventory, not an ordinary execution gate. Malformed or
-internally inconsistent selected projection data rejects with
-`ARCANE_RUNTIME_PROJECTION_INVALID`.
+Selected app files are emitted beneath `apps/<id>/`; shared files retain their
+configured route destinations. When selected shared content supplies no root
+`index.html`, the SDK generates one that opens the selected app page. The result
+contains `outputRoot`, `manifest`, and the complete `files` inventory.
+`manifest.app.entry` stays app-relative, while `manifest.app.start`
+is the package launch URL, such as `./apps/hello-world/index.html`. Release
+schema `1`, kind `arcane-app-release`, and packager identity
+`arcane-app-packager-v1` remain unchanged. A dry run returns the planned output
+and file inventory without writing source or output.
 
 ### Availability and normalization
 
@@ -808,7 +809,7 @@ const packaged = await packageApp({
     appId: 'hello-world'
 });
 
-console.log(packaged.importMap.documentPaths);
+console.log(packaged.manifest.app.start, packaged.files);
 ```
 
 ## PACKAGER_VERSION
@@ -4038,17 +4039,19 @@ console.log(result.importMap.documentPaths, result.importMap.documentCount);
 ### Overview
 
 Runs the high-level package operation for one selected application. It reads
-the installed SDK/runtime selection, injects one deterministic
-managed import map into every directly navigable included `.html`/`.htm`
-browser document while preserving component fragments as package files, and
-then packages the complete selected content without automatically running tests
-or checks. Verification occurs only when explicitly requested or when required
-for the selected release output. A failure leaves the previously accepted
-distribution untouched. Success returns the low-level package result and
-complete import-map document inventory. External
-packages publish `ARCANE_RUNTIME_PROJECTION.json`; private
-`ARCANE_APP_RELEASE.json` remains an internal verification authority rather
-than an application route.
+the installed SDK/runtime selection and packages the saved source and managed
+import maps through `packageApp()`. Map generation remains the explicit
+`arcane import-map` operation and the ordinary `arcane dev` startup refresh.
+Selected app files retain their `apps/<id>/` paths alongside the shared routes
+and root launcher described by `packageApp()`.
+
+Packaging does not automatically run tests or checks. Verification occurs only
+when explicitly requested or when required for the selected release output.
+A failure leaves the prior distribution untouched. Success returns the selected
+workspace and app identity plus `release`, containing the low-level package
+result, manifest, and complete file inventory. `ARCANE_APP_RELEASE.json` records
+that inventory and the distinct app-relative `app.entry` and package-relative
+`app.start`; it remains package metadata rather than an application route.
 
 ### Signature and result
 
@@ -4072,7 +4075,7 @@ const result = await packageApplication({
     appId: 'hello-world'
 });
 
-console.log(result.release.importMap.documentPaths);
+console.log(result.release.manifest.app.start, result.release.files);
 ```
 
 ## planApplication()