@jskit-ai/agent-docs 0.1.26 → 0.1.28

package/DISTR_AGENT.md

@@ -31,6 +31,7 @@ Core rules:
 - Keep that checkpoint compact. Do not expand it into a long preamble unless the developer asks for detail.
 - When a request involves JSKIT UI, routing, surfaces, CRUDs, filters, placements, live actions, or similar implementation details, scan `patterns/INDEX.md` for matching keywords and read only the relevant pattern files.
 - Reuse existing JSKIT helpers and runtime seams before adding new local helpers.
+- If `npm install` is run while the app is using local JSKIT checkout links, run `npm run devlinks` immediately afterward.
 - A freshly scaffolded JSKIT app can still be in Stage 1. If platform decisions are not settled yet, continue with the initialize workflow before adding runtime packages.
 - Do not treat a missing `config.tenancyMode` line or an untouched minimal scaffold as a final tenancy decision.
 - Do not install tenancy-sensitive packages until Stage 1 decisions are complete and the chosen tenancy is written into `config/public.js`.

package/guide/agent/app-extras/assistant.md

@@ -389,7 +389,7 @@ In the `page` subcommand:
 
 - the target file path decides the route location
 - `--name` changes the generated menu label
-- `--link-placement`, `--link-component-token`, and `--link-to` are optional overrides if you want to place the route link somewhere other than the generator's normal inferred target
+- `--link-placement` and `--link-to` are optional overrides if you want to place the route link somewhere other than the generator's normal inferred semantic target
 
 ## Generating the assistant settings pages
 
@@ -398,23 +398,17 @@ Now create the three settings pages:
 ```bash
 npx jskit generate assistant settings-page \
   console/settings/assistant/index.vue \
-  --surface console \
-  --link-placement console-settings:primary-menu \
-  --link-component-token local.main.ui.surface-aware-menu-link-item
+  --surface console
 
 npx jskit generate assistant settings-page \
   console/settings/admin-assistant/index.vue \
   --surface admin \
-  --name "Admin Assistant" \
-  --link-placement console-settings:primary-menu \
-  --link-component-token local.main.ui.surface-aware-menu-link-item
+  --name "Admin Assistant"
 
 npx jskit generate assistant settings-page \
   w/[workspaceSlug]/admin/workspace/settings/app-assistant/index.vue \
   --surface app \
-  --name "App Assistant" \
-  --link-placement admin-settings:primary-menu \
-  --link-component-token local.main.ui.surface-aware-menu-link-item
+  --name "App Assistant"
 ```
 
 This is the part that often trips people up, so read the rule carefully:
@@ -443,19 +437,14 @@ import { AssistantSettingsClientElement } from "@jskit-ai/assistant-runtime/clie
 
 The file path decides where the settings screen is opened. `target-surface-id` decides which assistant it edits.
 
-The extra link options matter here too:
+The inferred placement matters here too:
 
-- `--link-placement`
-  - which settings menu outlet should receive the generated link
-- `--link-component-token`
-  - which link component token should render that menu entry
 - `--name`
   - the label shown for the settings entry
 
-That is why the chapter uses:
+The console settings pages live under the console settings host, so JSKIT infers `page.section-nav` with owner `console-settings`. The workspace settings page lives under the admin workspace settings host, so JSKIT infers `page.section-nav` with owner `admin-settings`.
 
-- `console-settings:primary-menu` for the two console-owned settings screens
-- `admin-settings:primary-menu` for the workspace-admin-owned settings screen
+The concrete outlet and link renderer come from topology. Those settings hosts map `page.section-nav` to their concrete menus in `src/placementTopology.js`, so the commands do not need renderer flags.
 
 ## What to look at in the browser
 
@@ -466,7 +455,7 @@ npm run dev
 npm run server
 ```
 
-After sign-in, the app should now expose these assistant routes:
+After sign-in, the app should expose these assistant routes:
 
 - `/console/assistant`
 - `/w/your-personal-slug/admin/assistant`
@@ -545,7 +534,7 @@ That is what lets one app host several assistants at once without their AI setti
 
 ### `.env` gains one AI block per assistant surface
 
-The app now gets env keys such as:
+The app gets env keys such as:
 
 ```dotenv
 CONSOLE_ASSISTANT_AI_PROVIDER=openai

package/guide/agent/app-extras/mobile-capacitor.md

@@ -0,0 +1,381 @@
+<!-- Generated by `npm run agent-docs:build` from `packages/agent-docs/site/guide/app-extras/mobile-capacitor.md`. Do not edit manually. -->
+
+# Mobile Capacitor
+
+This chapter explains how to put a JSKIT app on an Android phone with the
+Capacitor shell.
+
+The normal result is:
+
+- your JSKIT web app runs inside an Android shell
+- the app can talk to your backend
+- deep links and auth callback routing still go through normal JSKIT routes
+- you can rebuild, reinstall, tunnel, and restart with `jskit mobile ...`
+
+## Install it
+
+From the app root:
+
+```bash
+npx jskit add package @jskit-ai/mobile-capacitor
+```
+
+That command:
+
+- installs `@jskit-ai/mobile-capacitor`
+- installs the required Capacitor packages
+- seeds `config.mobile` if it is missing
+- renders `capacitor.config.json`
+- provisions `android/`
+- refreshes the managed Android shell files from `config.mobile`
+
+After that, run:
+
+```bash
+npx jskit mobile android doctor
+```
+
+If doctor passes, the app is ready for the normal mobile workflow.
+The `jskit mobile android ...` commands expect the mobile runtime package to be
+installed in `package.json` and recorded in `.jskit/lock.json`; they do not
+install `@jskit-ai/mobile-capacitor` for you.
+
+## What you need on your machine
+
+::: tip Required Host Tools
+Before this workflow is healthy, the machine needs all of the following:
+
+- `adb` on `PATH`
+- Android SDK installed, with the required platform and build-tools
+- a full JDK, not just a runtime
+- `java` on `PATH`
+- `javac` on `PATH`
+- `ANDROID_HOME` or `ANDROID_SDK_ROOT` set, or `android/local.properties` with `sdk.dir=...`
+- `JAVA_HOME` pointing at a full JDK if `java` / `javac` are not already resolved correctly from `PATH`
+
+The end state should be:
+
+- `adb devices -l` works
+- `java -version` works
+- `javac -version` works
+- `npx jskit mobile android doctor` passes
+:::
+
+If you installed Android Studio, its bundled JDK is often the easiest working
+Java home:
+
+```bash
+export JAVA_HOME="$HOME/android-studio/jbr"
+export PATH="$JAVA_HOME/bin:$PATH"
+```
+
+## Put the app on your phone
+
+Start the backend first:
+
+```bash
+PORT=3000 npm run server
+```
+
+Then use the all-in-one command:
+
+```bash
+npx jskit mobile android dev
+```
+
+This is the one-stop shop for local Android phone testing.
+
+It runs these commands in this exact order:
+
+```bash
+npx jskit mobile android sync
+npx jskit mobile android tunnel
+npx jskit mobile android run
+```
+
+That first step is important: for bundled apps, `npx jskit mobile android sync` runs `npm run build` first and then runs `cap sync android`. So yes, `npx jskit mobile android dev` does build the app before it installs/runs the Android shell.
+
+If more than one Android device is attached:
+
+```bash
+npx jskit mobile android devices
+npx jskit mobile android dev --target <device-id>
+```
+
+That is the shortest path.
+
+## Manual commands
+
+If you want to run the steps yourself instead of using `mobile android dev`,
+these are the commands that matter.
+
+### List devices
+
+```bash
+npx jskit mobile android devices
+```
+
+Prints the Android devices currently visible to `adb`.
+
+### Sync the Android shell
+
+```bash
+npx jskit mobile android sync
+```
+
+This:
+
+- refreshes the managed mobile files from `config.mobile`
+- builds the JSKIT web app into `dist/`
+- runs `cap sync android`
+
+The refresh step requires the managed files from the package install to exist.
+If `capacitor.config.json` or `.jskit/mobile-capacitor.md` is missing, install
+the package again with `npx jskit add package @jskit-ai/mobile-capacitor`.
+
+### Create the local tunnel
+
+```bash
+npx jskit mobile android tunnel
+```
+
+If you want a specific device:
+
+```bash
+npx jskit mobile android tunnel --target <device-id>
+```
+
+This command creates the `adb reverse` tunnel that lets the phone reach your
+laptop's local backend.
+
+### Install and run the app
+
+```bash
+npx jskit mobile android run
+```
+
+Or:
+
+```bash
+npx jskit mobile android run --target <device-id>
+```
+
+This launches the Android shell through Capacitor.
+
+### Restart cleanly
+
+```bash
+npx jskit mobile android restart
+```
+
+Or:
+
+```bash
+npx jskit mobile android restart --target <device-id>
+```
+
+This:
+
+- clears app data
+- force-stops the Android app
+- cold-starts `MainActivity`
+
+Use it when you want a clean signed-out state.
+
+## The command set
+
+These are the CLI mobile commands used by the package workflow:
+
+- `jskit mobile android devices`
+  - list visible Android devices
+- `jskit mobile android doctor`
+  - validate config, shell files, SDK, and host readiness
+- `jskit mobile android dev`
+  - run the standard local-phone development flow
+- `jskit mobile android sync`
+  - rebuild and sync the Android shell
+- `jskit mobile android tunnel`
+  - create and verify the `adb reverse` tunnel
+- `jskit mobile android run`
+  - launch the Android shell
+- `jskit mobile android restart`
+  - clear app data and cold-start the app
+- `jskit mobile android build`
+  - build the Android release bundle
+
+## The default local-dev setup
+
+When `jskit add package @jskit-ai/mobile-capacitor` seeds `config.mobile` for the first time, it
+creates a working local-dev default.
+
+The important part is:
+
+```js
+config.mobile = {
+  enabled: true,
+  strategy: "capacitor",
+  assetMode: "bundled",
+  apiBaseUrl: "http://127.0.0.1:3000",
+  auth: {
+    callbackPath: "/auth/login",
+    customScheme: "your-app-slug"
+  }
+};
+```
+
+That default is good for local phone development against your laptop.
+
+It also means:
+
+- the backend must be running on your laptop
+- the app needs an `adb reverse` tunnel
+
+If `apiBaseUrl` later points to a real remote `https://...` backend, the tunnel
+is no longer required.
+
+## A good day-to-day loop
+
+Once the package is installed, the normal loop is:
+
+```bash
+PORT=3000 npm run server
+npx jskit mobile android dev
+```
+
+If you want to rerun steps manually, a predictable sequence is:
+
+```bash
+npx jskit mobile android sync
+npx jskit mobile android tunnel
+npx jskit mobile android run
+```
+
+And if you need a clean state afterward:
+
+```bash
+npx jskit mobile android restart
+```
+
+## Behind the scenes
+
+### `config.mobile` is the source of truth
+
+The Android shell is not configured by hand in scattered native files. JSKIT
+renders the shell from `config.mobile`.
+
+That config drives:
+
+- Capacitor app id and app name
+- Android package name
+- app version values
+- API base URL
+- auth callback path
+- custom URL scheme
+
+### The shell is still a JSKIT web app
+
+The UI still comes from the JSKIT web client.
+
+Stage 1 mobile does not turn JSKIT into a native UI framework. It packages the
+web app into a Capacitor Android shell.
+
+That is why `jskit mobile android sync` still builds the web app first.
+
+### Managed files
+
+The package manages:
+
+- `capacitor.config.json`
+- `.jskit/mobile-capacitor.md`
+- the Android shell under `android/`
+- managed Android identity files such as:
+  - `android/app/build.gradle`
+  - `android/variables.gradle`
+  - `android/app/src/main/res/values/strings.xml`
+  - `MainActivity.java` or `MainActivity.kt`
+- the managed deep-link block in `AndroidManifest.xml`
+
+After the package is installed, `jskit mobile android sync` refreshes those
+managed files from `config.mobile`.
+
+### Why the tunnel exists
+
+Inside the Android shell, the phone's `127.0.0.1` is the phone itself, not your
+laptop.
+
+So when local development uses:
+
+```text
+http://127.0.0.1:3000
+```
+
+the phone still needs a bridge back to your laptop.
+
+That bridge is:
+
+```bash
+adb reverse tcp:3000 tcp:3000
+```
+
+`jskit mobile android tunnel` wraps that and shows `adb reverse --list`
+afterward so you can see the active mapping.
+
+### What happens to URLs
+
+Inside the Capacitor shell there are two relevant URL worlds:
+
+- shell/webview origin:
+  - `https://localhost/...`
+- backend/API origin:
+  - usually `config.mobile.apiBaseUrl`
+
+JSKIT keeps app code using normal relative server paths such as:
+
+- `/api/session`
+- `/api/bootstrap`
+- `/socket.io/...`
+
+The mobile runtime adapts those requests to the configured backend origin.
+
+That is why app code does not need a separate "mobile API client" pattern for
+the standard JSKIT server routes.
+
+### Why local HTTP works on Android
+
+For the local-dev case, the backend URL is often plain `http`.
+
+The mobile shell therefore needs:
+
+- Capacitor native HTTP enabled
+- Android cleartext traffic allowed for the generated shell
+
+Without those, Android or the WebView will block local backend traffic even if
+the tunnel itself is correct.
+
+### Auth and deep links
+
+The mobile shell does not invent a separate auth route system.
+
+The normal contract stays:
+
+- OAuth start opens in the external browser/custom tab
+- callback returns through the app's custom scheme
+- callback path is still the normal JSKIT path:
+  - `/auth/login`
+
+Deep links and auth completion are normalized back into the normal JSKIT router.
+
+### What `doctor` is actually checking
+
+`jskit mobile android doctor` is the preflight command for this whole lane.
+
+It checks:
+
+- `config.mobile`
+- managed shell file freshness
+- Android shell presence
+- deep-link wiring
+- Android SDK basics
+- host readiness for the shell path
+
+If mobile work looks strange, run doctor first.

package/guide/agent/app-extras/realtime.md

@@ -21,13 +21,13 @@ The first command records the runtime package in the app and updates the existin
 
 Unlike the database, users, console, and workspace chapters, this one does **not** need `npm run db:migrate`. `realtime` does not add schema files. It is transport infrastructure, not persistence.
 
-## What changes now
+## What the package adds
 
-Installing `realtime` changes the app in three important ways.
+Installing `realtime` adds three app capabilities.
 
 ### The app gets a realtime transport
 
-The server now mounts a socket.io runtime on the same Fastify server that already serves your JSKIT surfaces. The browser gets a matching socket.io client runtime through the normal client boot process.
+The server mounts a socket.io runtime on the same Fastify server that already serves your JSKIT surfaces. The browser gets a matching socket.io client runtime through the normal client boot process.
 
 That means later modules, or your own app code, can stop thinking only in terms of request/response HTTP flows. They can start publishing live events and listening for them in Vue.
 
@@ -35,7 +35,7 @@ That means later modules, or your own app code, can stop thinking only in terms
 
 The package also uses the shell scaffolding that already exists.
 
-`realtime` appends a placement entry into `src/placement.js` that targets `shell-layout:top-right`, so the shell starts showing a small status dot without you having to create a new page for it.
+`realtime` appends a placement entry into `src/placement.js` that targets the semantic `shell.status` placement, so the shell shows a small status dot without you having to create a new page for it. In the default shell topology, `shell.status` renders through the concrete `shell-layout:top-right` outlet.
 
 That dot is:
 
@@ -52,7 +52,7 @@ The app already had a browser dev server on `5173` and a backend runtime on `300
 
 So one of the main values of this package is that you do **not** have to hand-edit Vite config just to make socket.io work in local development.
 
-### There are still no new pages
+### There are no realtime pages
 
 This is worth saying clearly because it can otherwise feel surprising.
 
@@ -75,7 +75,7 @@ npm run server
 
 Then open `http://localhost:5173/home`.
 
-The important visible change is in the top-right of the shell. You should now see the realtime status dot alongside the other shell controls.
+The visible check is the shell status area. You should see the realtime status dot alongside the other shell controls.
 
 If the websocket connects successfully, the dot is green. If the backend is unavailable or the socket is reconnecting, the dot is red. Hovering it shows the current status text.
 
@@ -159,14 +159,15 @@ After the install, the app has:
 
 That one entry is what lets the browser dev server proxy websocket traffic correctly during local development.
 
-### `src/placement.js` grows one new shell placement
+### `src/placement.js` includes the shell status placement
 
 The package appends this placement:
 
 ```js
 addPlacement({
   id: "realtime.connection.indicator",
-  target: "shell-layout:top-right",
+  target: "shell.status",
+  kind: "component",
   surfaces: ["*"],
   order: 950,
   componentToken: "realtime.web.connection.indicator"
@@ -215,9 +216,9 @@ That is the right level of abstraction for this package:
 
 ## Summary
 
-This chapter does not make the app look radically different, but it adds an important new capability.
+This chapter does not make the app look radically different, but it adds an important capability.
 
-- the backend can now host a realtime socket server
-- the frontend can now keep one shared websocket connection alive
-- the shell now exposes a live connection indicator
+- the backend hosts a realtime socket server
+- the frontend keeps one shared websocket connection alive
+- the shell exposes a live connection indicator
 - later modules can build live behavior on top of that transport without inventing their own websocket setup