arcane-os 0.29.1 → 0.31.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.31.0
+
+- Standalone applications use their repository root and installed npm package
+  paths. New standalone projects default to `appsRoot: "."`; initialization
+  preserves an existing configured layout, and explicit multi-app workspaces
+  retain their selected application directories.
+- Remove the retired `legacyAppPaths` setting and all SDK-generated nested app
+  redirects and duplicate PWA worker/inventory files. Consumers must remove the
+  obsolete setting when upgrading. Enabled PWA files remain at the app root;
+  public SDK files remain under `node_modules/arcane-os` or the installed alias.
+- Preserve selected authored files, complete URLs and queries, installation
+  identity, saved data and caches. Generation does not delete preexisting app
+  files; application owners preserve and relocate their content independently.
+- Generated and offline app files are committed for hosting workflows to
+  consume. Existing public Node TWiN and browser APIs remain available.
+
+## 0.30.0
+
+- Add the public `arcane-os/ai/twin-cloud` subpath with stateless `fetchRequest`
+  for Node and browser callers. Supply the TWiN key, model, messages, optional
+  structured-output schema and cancellation signal explicitly. The result is
+  the complete parsed provider completion, with no browser startup, saved
+  conversation, hidden model default or output cap.
+- Share the existing TWiN HTTP, structured JSON, overload retry and cancellation
+  implementation with the browser AI owner while preserving its public methods
+  and lifecycle. Only overload responses with HTTP 429 use the existing
+  three-second retry; other failures retain their complete provider response.
+
 ## 0.29.1
 
 - Preserve complete long and non-ASCII filenames in application release bundles

package/README.md

@@ -16,31 +16,34 @@
 `arcane-os` is the application SDK and command-line toolchain for Arcane OS. It
 supports two explicit workspace profiles: an external app repository uses the
 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.
+`arcane/` runtime. Both profiles share the theme, packaging, event, cancellation,
+and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.29.1` SDK contract. Applications pin one exact npm
+This checkout defines the `0.31.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
-External browser apps can use the installed npm package directly, without a
+Standalone browser apps use their repository root and installed npm package directly, without a
 generated workspace `arcane/` directory or `arcane.lock.json`. Select the
 [four installed-package routes](docs/reference/protocols.md#installed-package-browser-routes)
 in `arcane-packager.json`: development, managed import maps, and PWA resources
 read the installed SDK at real `/node_modules/arcane-os/...` browser URLs when
 each destination equals its source. An alias uses its actual installed folder.
-Select `appsRoot: "."` for a standalone root app, or scaffold one with
-`arcane new my-app --apps-root .`. After npm installation, `arcane import-map`
-refreshes managed maps and the root app's static PWA/navigation files for ordinary
-static hosting. Portable app packages still contain their selected runtime.
+`arcane new my-app` defaults to `appsRoot: "."`. After npm installation,
+`arcane import-map` refreshes managed maps and the enabled root PWA files for
+ordinary static hosting. It generates no nested app redirects or duplicate PWA
+files. Remove the retired `legacyAppPaths` setting when upgrading. Commit generated
+and offline app files for hosting workflows to consume. Portable app packages
+still contain their selected runtime.
 Root/direct maps use `arcane-os/modules/<filename>` and
 `arcane-os/entities/<filename>` (including extensions) plus the focused lowercase
 exports, rather than `arcane/*` aliases. These paths resolve to the actual npm
 files, preserving relative component URLs. New root apps put the SDK in runtime
 `dependencies`; init preserves existing runtime/optional declarations and promotes
 a root app's SDK development declaration without changing its other packages.
-Existing `apps/<id>`, virtual `/arcane` routes, and materialized workspaces remain
-supported. Node services continue to
+Explicit multi-app `appsRoot: "apps"`, virtual runtime routes, and existing
+materialized workspaces remain supported; initialization preserves their selected
+layout. Node services continue to
 use the installed CLI or public imports such as `arcane-os/mail`.
 
 The [mail gateway](docs/reference/mail.md) serves HTTPS with HTTP/2 on port 4433
@@ -82,7 +85,7 @@ Create one browser application, install its pinned SDK, and start its source
 server:
 
 ```bash
-npx arcane-os@0.26.0 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.31.0 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 ```

package/browser-runtime/ai/browser-device-settings.mjs

@@ -74,11 +74,11 @@ export function getBrowserDeviceSettings(navigatorObject = globalThis.navigator)
 
 // Only an explicit browser adapter type or fallback flag establishes its class.
 // Vendor names and powerPreference (including Chromium's echoed request) do not.
-export function describeBrowserGpu(info, legacyFallbackAdapter) {
+export function describeBrowserGpu(info, fallbackAdapter) {
     const adapterType = is.string(info?.type) ? info.type : null;
     const isFallbackAdapter = is.boolean(info?.isFallbackAdapter)
         ? info.isFallbackAdapter
-        : is.boolean(legacyFallbackAdapter) ? legacyFallbackAdapter : null;
+        : is.boolean(fallbackAdapter) ? fallbackAdapter : null;
     let performanceStatus = 'unknown';
     if (isFallbackAdapter === true || adapterType === 'CPU') performanceStatus = 'fallback';
     else if (adapterType === 'discrete GPU') performanceStatus = 'discrete';

package/browser-runtime/ai/twin-cloud.mjs

@@ -0,0 +1,230 @@
+import Is from 'strong-type';
+import {arcaneLogging} from '../logging.mjs';
+
+const is = new Is(false);
+const twinChatURL = 'https://inference.do-ai.run/v1/chat/completions';
+
+/** A stateless TWiN request; browser AI shares the HTTP and format owners below. */
+export async function fetchRequest({
+    twinKey,
+    model,
+    messages = [],
+    structuredOutput = false,
+    tools = [],
+    toolChoice = 'auto',
+    parallelToolCalls,
+    reasoningEffort,
+    signal = null,
+    id = Date.now(),
+    onRequest = function observeTWiNRequest(){},
+    onResponse = function observeTWiNResponse(){}
+} = {}){
+    if(signal?.aborted){
+        throw normalizeAIRequestAbort(signal.reason);
+    }
+    if(!is.string(twinKey) || !twinKey){
+        const error = new Error('AI provider is not configured.');
+        error.code = 'AI_PROVIDER_NOT_CONFIGURED';
+        throw error;
+    }
+    if(!is.string(model) || !model){
+        throw new TypeError('TWiN fetchRequest requires an explicit model.');
+    }
+
+    const request = {model, messages, stream:false};
+    const format = structuredOutputFormat(structuredOutput);
+    if(format){
+        request.response_format = openAIResponseFormat(format);
+    }
+    if(tools.length){
+        request.tools = tools;
+        request.tool_choice = toolChoice;
+        if(parallelToolCalls !== undefined){
+            request.parallel_tool_calls = parallelToolCalls;
+        }
+    }
+    if(reasoningEffort){
+        request.reasoning_effort = reasoningEffort;
+    }
+
+    try{
+        await onRequest(
+            request,
+            id,
+            {operation:'fetch', transport:'http', destination:twinChatURL}
+        );
+        if(signal?.aborted){
+            throw normalizeAIRequestAbort(signal.reason);
+        }
+        const response = await fetchJSONResponse(
+            twinChatURL,
+            {
+                method:'POST',
+                credentials:'omit',
+                headers:{
+                    'Content-Type':'application/json',
+                    Authorization:`Bearer ${twinKey}`
+                },
+                body:JSON.stringify(request),
+                ...(signal ? {signal} : {})
+            }
+        );
+        if(signal?.aborted){
+            throw normalizeAIRequestAbort(signal.reason);
+        }
+        await onResponse(response, id, false);
+        if(signal?.aborted){
+            throw normalizeAIRequestAbort(signal.reason);
+        }
+        return response;
+    }catch(error){
+        if(isAIRequestAbort(error, signal)){
+            throw normalizeAIRequestAbort(error);
+        }
+        throw error;
+    }
+}
+
+export function isAIRequestAbort(error, signal){
+    return signal?.aborted
+        || error?.name === 'AbortError'
+        || error?.code === 'ARCANE_REQUEST_ABORTED'
+        || error?.code === 'ARCANE_AI_REQUEST_ABORTED'
+        || error?.code === 'AI_REQUEST_ABORTED';
+}
+
+export function normalizeAIRequestAbort(error){
+    if(error?.code === 'ARCANE_AI_REQUEST_ABORTED'){
+        return error;
+    }
+    const normalized = new Error('The AI request was cancelled.', {cause:error});
+    normalized.name = 'AbortError';
+    normalized.code = 'ARCANE_AI_REQUEST_ABORTED';
+    return normalized;
+}
+
+export function structuredOutputFormat(value = false){
+    if(value === false || value === null || value === undefined){
+        return null;
+    }
+    if(value === true || value === 'json'){
+        return 'json';
+    }
+    if(
+        is.object(value)
+        && !is.array(value)
+        && (
+            Object.getPrototypeOf(value) === Object.prototype
+            || Object.getPrototypeOf(value) === null
+        )
+    ){
+        return value;
+    }
+    const error = new TypeError(
+        'AI structured output must be enabled with true, json, or a JSON Schema object.'
+    );
+    error.code = 'AI_STRUCTURED_OUTPUT_INVALID';
+    throw error;
+}
+
+export function openAIResponseFormat(format){
+    if(format === 'json'){
+        return {type:'json_object'};
+    }
+    if(format){
+        return {
+            type:'json_schema',
+            json_schema:{name:'structured_response', strict:true, schema:format}
+        };
+    }
+    return null;
+}
+
+/** Shared with browser streaming; consume no successful body at this boundary. */
+export async function fetchHTTPResponse(url, options){
+    const {signal} = options;
+    const retryDelayMs = 3000;
+    try{
+        while(true){
+            if(signal?.aborted){
+                throw normalizeAIRequestAbort(signal.reason);
+            }
+            const response = await fetch(url, options);
+            if(signal?.aborted){
+                throw normalizeAIRequestAbort(signal.reason);
+            }
+            if(response.ok){
+                return response;
+            }
+            const contentType = response.headers.get('content-type') || '';
+            const error = contentType.includes('application/json')
+                ? await response.json()
+                : await response.text();
+            if(signal?.aborted){
+                throw normalizeAIRequestAbort(signal.reason);
+            }
+            const message = is.string(error)
+                ? error
+                : error?.error?.message ?? error?.message;
+            if(
+                response.status !== 429
+                || !is.string(message)
+                || !message.toLowerCase().includes('overload')
+            ){
+                throw error;
+            }
+            arcaneLogging.warn(
+                `${message}\nRetrying in ${retryDelayMs / 1000} seconds`,
+                error
+            );
+            await new Promise(function waitForOverloadRetry(resolve, reject){
+                function finishRetryDelay(){
+                    signal?.removeEventListener('abort', cancelRetryDelay);
+                    resolve();
+                }
+                function cancelRetryDelay(){
+                    clearTimeout(timer);
+                    signal.removeEventListener('abort', cancelRetryDelay);
+                    reject(normalizeAIRequestAbort(signal.reason));
+                }
+                const timer = setTimeout(finishRetryDelay, retryDelayMs);
+                signal?.addEventListener('abort', cancelRetryDelay, {once:true});
+                if(signal?.aborted){
+                    cancelRetryDelay();
+                }
+            });
+        }
+    }catch(error){
+        if(isAIRequestAbort(error, signal)){
+            throw normalizeAIRequestAbort(error);
+        }
+        throw error;
+    }
+}
+
+/** Return the entire parsed completion without selecting or rewriting choices. */
+export async function fetchJSONResponse(url, options){
+    const {signal} = options;
+    try{
+        const response = await fetchHTTPResponse(url, options);
+        if(signal?.aborted){
+            throw normalizeAIRequestAbort(signal.reason);
+        }
+        const contentType = response.headers.get('content-type') || '';
+        if(!contentType.includes('application/json')){
+            throw new TypeError(
+                `AI request returned ${contentType || 'an unknown content type'} instead of JSON.`
+            );
+        }
+        const completion = await response.json();
+        if(signal?.aborted){
+            throw normalizeAIRequestAbort(signal.reason);
+        }
+        return completion;
+    }catch(error){
+        if(isAIRequestAbort(error, signal)){
+            throw normalizeAIRequestAbort(error);
+        }
+        throw error;
+    }
+}

package/docs/reference/ai/twin-cloud.md

@@ -1,8 +1,125 @@
 # TWiN Cloud: one request
 
-TWiN Cloud is the high-level `AI.js` default remote LLM service, named `TWIN`.
-Speech stays on device and does not use the TWiN access key. This guide uses the
-same managed browser imports as the [browser speech quick start](browser-speech.md).
+Use `fetchRequest` from `arcane-os/ai/twin-cloud` for a complete TWiN Cloud
+request in Node or a browser with an explicit key and model. It imports no
+browser profile, DOM, user singleton, or storage, and starts no work on import.
+The existing browser `AI.js` interface remains available for applications that
+already use its provider selection, lifecycle, and speech. TWiN Cloud is that
+interface's default remote LLM service, named `TWIN`; speech stays on device
+and does not use the TWiN access key.
+
+## Node: explicit key, model, and structured result
+
+Install the published `arcane-os` package in the Node project. Keep the key in
+the application's existing server configuration, outside source control and
+diagnostics. In this example, `server-config.json` is that caller-owned local
+configuration file with a `twinKey` property; add its exact path to `.gitignore`
+before creating it. The SDK does not discover or write this file.
+
+```javascript
+import serverConfig from './server-config.json' with {type: 'json'};
+import {fetchRequest} from 'arcane-os/ai/twin-cloud';
+
+const response = await fetchRequest({
+    twinKey: serverConfig.twinKey,
+    model: 'openai-gpt-oss-20b',
+    messages: [{
+        role: 'user',
+        content: 'Explain why the moon-powered toaster keeps burning breakfast. Return HTML and plain text.'
+    }],
+    structuredOutput: {
+        type: 'object',
+        properties: {
+            html: {type: 'string'},
+            text: {type: 'string'}
+        },
+        required: ['html', 'text'],
+        additionalProperties: false
+    }
+});
+
+console.log(response);
+```
+
+`model` is required and remains exactly the supplied identifier. This function
+does not select the browser profile's default model. The example's prompt and
+`html`/`text` schema are caller-owned data, not SDK business logic. Changing
+those fields changes the requested result without changing the SDK.
+
+The resolved value is the complete parsed provider JSON, including every
+choice and provider field. The SDK does not extract only the first message,
+parse its content into a second object, or replace the response with an
+application-specific record. The supplied schema becomes
+`response_format: {type:'json_schema', json_schema:{name:'structured_response',
+strict:true, schema:...}}`. `structuredOutput:true` or `'json'` instead selects
+`response_format:{type:'json_object'}`; omission leaves structured output off.
+
+## Shared request behavior
+
+The focused API accepts complete `messages`, optional `tools`, `toolChoice`,
+`parallelToolCalls`, and `reasoningEffort` in addition to the explicit
+`twinKey` and `model`. Tool options use the existing chat-completion wire fields
+`tools`, `tool_choice`, and `parallel_tool_calls` when `tools` is nonempty.
+A supplied nonempty `reasoningEffort` uses the provider's `reasoning_effort`
+field; omission preserves its default. No output limit is added by this API.
+The function neither executes tools nor adds provider-response envelope
+validation.
+
+Optional `id`, `onRequest(request,id,metadata)`, and
+`onResponse(response,id,false)` follow the complete-response `AI.fetchRequest`
+callback shape. The request callback runs before dispatch; the response
+callback receives the complete parsed result before it is returned. Omitted
+`id` uses `Date.now()`; request metadata is
+`{operation:'fetch',transport:'http',destination:'https://inference.do-ai.run/v1/chat/completions'}`.
+The key is
+transport authentication, not part of either callback's message payload. Keep
+credentials out of application logging as well.
+
+Only HTTP `429` with a message containing `overload` (case-insensitive) repeats automatically,
+after `3000` milliseconds. Another overload repeats the same complete request;
+other HTTP failures do not become an automatic retry loop. Pass a fresh
+`AbortController`'s `signal` and call `abort()` to cancel. Cancellation during
+the request, response-body read, retry wait, or callback settlement prevents
+successful result delivery and rejects with `ARCANE_AI_REQUEST_ABORTED`.
+Other HTTP failures throw the complete parsed JSON error body or text body.
+A missing key uses `AI_PROVIDER_NOT_CONFIGURED`, a missing explicit model
+throws `TypeError`, and an unsupported `structuredOutput` input uses
+`AI_STRUCTURED_OUTPUT_INVALID`.
+
+The SDK retains no request or response history between calls and uses no
+DBOPFS, chat entity, or memory extraction. Each call's `messages` are its
+complete caller-supplied context. The caller decides whether and how to keep
+the result; this stateless transport adds no saved conversation or migration.
+
+Browser applications can use this same focused import through their generated
+managed import map. Browser Fetch and CORS behavior still apply. Importing it
+does not instantiate `AI`, read saved preferences, configure speech, or change
+the existing `arcane-os/ai` browser entry.
+
+### Shared low-level integration helpers
+
+The same module also exports the helpers used by browser `AI.js`. Ordinary
+callers use `fetchRequest`; these exports let SDK transport integration share
+the existing implementation rather than maintain another retry or body reader.
+
+| Export | Contract |
+| --- | --- |
+| `fetchHTTPResponse(url,options)` | Uses the caller's Fetch options, overload retry and cancellation; returns a successful `Response` with its body unconsumed. |
+| `fetchJSONResponse(url,options)` | Uses that HTTP owner, requires `application/json`, and returns the complete parsed body without selecting choices. |
+| `structuredOutputFormat(value=false)` | Maps false/null/undefined to null, true/`'json'` to `'json'`, and preserves a supplied plain JSON Schema object. Other inputs use `AI_STRUCTURED_OUTPUT_INVALID`. |
+| `openAIResponseFormat(format)` | Maps the normalized value to `json_object`, strict `json_schema` named `structured_response`, or null. |
+| `isAIRequestAbort(error,signal)` | Recognizes an aborted signal, `AbortError`, or the existing Arcane AI/request cancellation codes. |
+| `normalizeAIRequestAbort(error)` | Preserves an existing `ARCANE_AI_REQUEST_ABORTED` error or creates that `AbortError` with the original value as its cause. |
+
+These helpers start no work on import. HTTP helpers require explicit URL and
+options; they do not add a key, model, browser state, or retained conversation.
+Overload warnings use the shared console logger and preserve the complete
+provider error.
+
+## Existing browser AI interface
+
+The following browser example uses the same managed imports as the
+[browser speech quick start](browser-speech.md).
 
 ## Install and import
 

package/docs/reference/availability-and-normalization.md

@@ -78,6 +78,7 @@ version; WebKitGTK availability must not be generalized to macOS.
 | Read host identity, capabilities, storage, preferences, appearance, or platform state | `globalThis.Arcane` | **Cross-host** where the method is implemented and admitted | Promise behavior and `Arcane.Error` are normalized. Result fields are normalized unless the method explicitly documents a platform-dependent snapshot. |
 | Use local AI without coupling app code to Ollama HTTP | `Arcane.localAI`, `Arcane.ai`, or `/arcane/modules/Ollama.js` | Primarily **Native**; Android exposes a narrower admitted inference projection | Admission, errors, and managed-operation events are normalized. Direct Ollama response envelopes remain **Provider-native**. |
 | Use TWiN Cloud from the renderer profile | `/arcane/modules/AI.js` | **Cloud** from an allowed browser/native renderer | High-level chat behavior is normalized by the module. The TWiN access key authenticates remote LLM chat; raw provider diagnostics remain provider-specific. No automatic cloud fallback is inferred from local failure. |
+| Send one TWiN Cloud request with an explicit key and model | `fetchRequest` from `arcane-os/ai/twin-cloud` | **Node** and **Browser**, using standard Fetch and a remote HTTPS provider | Keeps complete messages and returns the full parsed provider JSON. Shared structured-output mapping, overload-only HTTP 429 retry after 3000 ms, and cancellation match browser TWiN transport. No browser profile, AI/user singleton, DBOPFS, or retained request history is created. |
 | Use speech through one application helper | `/arcane/modules/AI.js` and `Arcane.speech` | **Browser** or **Native** | The helper keeps audio on device: Whisper owns STT and Kokoro owns TTS. It automatically cleans only the outbound speech-input copy and normalizes application-facing audio/text behavior while browser and native request/response plumbing differs below that boundary. |
 | Inspect or manage raw Ollama models | `Arcane.ollama` or `/arcane/modules/Ollama.js` | **Native** desktop Core for management; narrower Android inference only | Wrapper method names, errors, streaming correlation, and admission are Arcane-controlled. Direct Ollama success envelopes are intentionally provider-native. |
 | Use native terminal, installation, user, provisioning, or machine controls | matching `Arcane.*` namespace | **Native** and app/capability restricted | Calls and errors use the common bridge contract. Platform results can be host-specific and are marked in the method guide. |
@@ -240,6 +241,14 @@ snapshot.
 
 ### Provider-native within an Arcane boundary
 
+[`arcane-os/ai/twin-cloud`](ai/twin-cloud.md) accepts an explicit `twinKey` and
+`model`, with the same named `fetchRequest` import in Node and managed browsers.
+It preserves complete provider response JSON while mapping the supplied
+structured-output, tool, and reasoning options to the TWiN wire contract.
+The SDK adds no output cap or persisted context. Cancellation applies during
+request, body read, overload retry wait, and callback settlement. The existing
+profile-backed browser `AI.js` entry and its lifecycle remain separate.
+
 Direct `Arcane.ollama.chat()`, `generate()`, `show()`, `embed()`, and lifecycle
 methods return complete Ollama-compatible envelopes. Arcane still owns error
 normalization, chunk correlation, and host transport, but it does

package/docs/reference/cli.md

@@ -120,8 +120,9 @@ directory as a repository. Native target scaffolds also retain `browser` and
 include the required icon. The result reports the workspace, app, descriptor,
 target, and created paths.
 
-`--apps-root .` creates a standalone root application using its installed npm
-SDK directly. The default `--apps-root apps` preserves `apps/<id>`. Root setup
+Each standalone app's root is its repository root. The default `--apps-root .`
+uses the installed npm SDK directly. Explicit `--apps-root apps` selects a
+multi-app workspace with each app beneath `apps/<id>`. Root setup
 does not install dependencies or copy a runtime: run `npm install`, then
 `npm run import-map`. Until installation, its result reports the import map as
 pending with reason `sdk-install-required`.
@@ -152,7 +153,7 @@ idempotent only for files whose existing content satisfies the scaffold
 contract.
 
 `--apps-root .` selects root setup for a standalone workspace. Omission retains
-the configured layout, or `apps` for a new configuration. `init` never moves an
+the configured layout, or `.` for a new standalone configuration. `init` never moves an
 existing application or converts the integrated Arcane OS layout.
 
 ### Example
@@ -217,8 +218,9 @@ the workspace does not already identify exactly one. The command accepts no
 positional arguments and supports app scope only. `arcane-os import-map` is the
 identical executable alias.
 
-The generated artifact is
-`apps/<id>/modules/arcane.importmap.json`. Its exact JSON is also installed in
+The generated artifact is `modules/arcane.importmap.json` at a standalone
+app's repository root, or `apps/<id>/modules/arcane.importmap.json` for an
+explicit multi-app workspace. Its exact JSON is also installed in
 the configured entry and every other admitted browser document as `<script
 type="importmap" data-arcane-import-map>` before module loading. The complete
 runtime map derives its entries from the selected runtime and browser-runtime
@@ -228,15 +230,13 @@ portable runtime subpaths such as `arcane-os/preference-store` and
 modules. The result reports the complete map written to the selected
 application; no fixed entry count is a release contract.
 
-For `appsRoot: "."`, the artifact is `modules/arcane.importmap.json` at the
-application root. Set `"legacyAppPaths": false` in `arcane-packager.json` to
-omit SDK-generated `apps/<id>/` navigation/PWA compatibility files and aliases.
-The same workspace choice applies to `arcane dev` and `arcane package`; restart
-an already running dev server after changing it. The default remains `true`.
-Root PWA files, app/installation identity and selected authored files are
-preserved. Existing files are never deleted by this option. See
-[root-only generated output](pwa.md#root-only-generated-output) before changing
-the URLs needed by previously installed apps.
+For `appsRoot: "."`, managed imports use the installed package paths and enabled
+PWA files are written beside the root entry. The SDK generates no nested
+`apps/<id>/` redirects or duplicate PWA files and no repository-root `arcane/`
+projection. App and installation identity, saved data, and selected authored
+files remain unchanged. The same layout applies to `arcane dev` and
+`arcane package`. Generated and offline app files are committed; GitHub Actions
+consume those committed files. See [root generated output](pwa.md#root-generated-output).
 
 SDK `0.5.17` preserves the physical workspace route count and ordered include
 list. External and modern integrated routes require `components`, `css`,
@@ -531,8 +531,9 @@ npm exec -- arcane check --app hello-world
 
 Creates one complete browser release beneath `dist/<id>/`, preserving the prior
 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
+import maps, keeps standalone app files at the output root, and retains the
+configured shared route destinations. Explicit multi-app workspaces retain
+their selected app beneath `apps/<id>/`. 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.
@@ -542,11 +543,10 @@ selected SDK content directly from `node_modules`. Only the portable output
 receives copies; no workspace `arcane/` projection is required. Its runtime URLs,
 managed import-map targets, and PWA inventory destinations match source serving.
 
-With `appsRoot: "."`, app files retain their root-relative layout. The optional
-root-config `legacyAppPaths: false` omits SDK-generated compatibility files
-beneath `apps/<id>/` from the planned and actual output. It does not omit
-explicitly selected authored resources at those paths or change the default
-packaged installation identity. Omission or `true` preserves existing behavior.
+With `appsRoot: "."`, the planned and actual output retain root-relative app
+files and direct npm package paths. The SDK adds no nested app redirects or
+duplicate PWA worker/inventory files. Explicitly selected authored resources
+and the default packaged installation identity remain unchanged.
 
 ```text
 arcane package [--app <id>] [--dry-run]
@@ -898,10 +898,10 @@ Resend key for all its requests. An absent named key never falls back to the
 default account. Existing root `RESEND_API_KEY` and
 `MAIL_PROFILES[name].RESEND_API_KEY` remain fallbacks when the corresponding
 nested key property is absent. A nested property containing null or an empty
-string means the selected key is absent and takes precedence over a legacy key.
+string means the selected key is absent and takes precedence over a root or profile key.
 
 Set and delete preserve the file's other settings and profile containers. New
-keys are written to the nested mail member. Existing legacy keys are updated
+keys are written to the nested mail member. Existing root or profile keys are updated
 in place unless the selected nested key property exists; delete removes both
 representations of only the selected key. Status returns the selected profile,
 `provider:'resend'`, `storage:'.arcane.env.json'`, and `exists`. Delete returns
@@ -963,7 +963,7 @@ paths. It consumes the configured provider timeout and retry guidance.
 
 The Resend credential comes from the selected `.arcane.env.json` entry.
 An explicit `--profile` overrides `arcane.config.json.mail.profile`; omitting
-both selects the default `mail.apiKey`, with the legacy fallback described
+both selects the default `mail.apiKey`, with the root-key fallback described
 above. Neither the key nor report content is accepted through argv or process
 environment variables.
 
@@ -1006,7 +1006,7 @@ Add the listener's certificate paths to `arcane.config.json`:
 
 Supply an existing PEM certificate chain and its private key. Paths resolve
 relative to the selected configuration directory, or may be absolute. They
-belong to the listener regardless of the provider key selected. Legacy root
+belong to the listener regardless of the provider key selected. Existing root
 `MAIL_TLS_CERT_PATH` and `MAIL_TLS_KEY_PATH` in `.arcane.env.json` remain
 fallbacks for omitted config paths. Explicit programmatic `certPath` and
 `keyPath` options override those files. Missing TLS settings name the fields