@jskit-ai/agent-docs 0.1.1

package/guide/agent/generators/ui-generators.md

@@ -0,0 +1,648 @@
+<!-- Generated by `npm run agent-docs:build` from `docs/guide/generators/ui-generators.md`. Do not edit manually. -->
+
+# UI Generators
+
+The earlier chapters already used `ui-generator` a little when we added:
+
+- the `Alerts Widget`
+- the `Profile` settings page
+- the `Notifications` settings page
+
+This chapter steps back and treats that tool as a subject in its own right.
+
+Use `ui-generator` when you want app-owned UI that is **not** a CRUD route tree.
+
+That usually means one of four jobs:
+
+- create a route page
+- create a small placed UI element
+- turn an existing page into a host for child routes
+- add a generic placement seam to an existing Vue file
+
+## `ui-generator` `@jskit-ai/ui-generator` `(0.1.22)`
+
+`ui-generator` has four subcommands:
+
+- `page`
+- `placed-element`
+- `add-subpages`
+- `outlet`
+
+They are all about app-owned UI, but they solve different problems.
+
+The easiest way to understand them is:
+
+- `page` creates a route and the link that reaches it
+- `placed-element` creates a reusable component and places it somewhere
+- `add-subpages` upgrades a page into a routed child-page host
+- `outlet` adds only a placement seam, without routed child-page behavior
+
+## The simplest case: `page`
+
+Start with the most common command:
+
+```bash
+npx jskit generate ui-generator page \
+  home/reports/index.vue \
+  --name "Reports"
+```
+
+This command creates a page at:
+
+```text
+src/pages/home/reports/index.vue
+```
+
+and it also appends a matching link placement into:
+
+```text
+src/placement.js
+```
+
+That second part is important. `page` is not just a file generator. It also makes the new page reachable inside the shell.
+
+In a fresh `home` surface app, the generated placement looks like a normal shell menu link. In the throwaway app used to verify this chapter, the command reported:
+
+```text
+Generated UI page "/reports" at src/pages/home/reports/index.vue.
+Touched files (2):
+- src/pages/home/reports/index.vue
+- src/placement.js
+```
+
+That is the baseline behavior of `page`:
+
+- one app-owned page file
+- one app-owned placement entry
+
+The important default is this:
+
+- if JSKIT sees no nearer routed host, the new page gets a normal shell/menu placement
+- if JSKIT does see a nearer routed host, the new page gets linked into that host instead
+
+Open the app and you now have a real `/reports` page plus a real shell link for it.
+
+### Customizing the generated menu link
+
+The generated page command does not ask for an icon up front. That is deliberate. The command's job is to create the route and the matching placement entry, not to force every menu detail during generation.
+
+If you want to customize the link afterwards, edit the placement entry that `page` wrote into `src/placement.js`.
+
+That is where things such as:
+
+- `label`
+- `order`
+- `icon`
+- a custom `componentToken`
+
+normally get adjusted.
+
+The important icon rule is this:
+
+- inside `src/placement.js` menu metadata, raw `mdi-*` strings are fine
+- inside normal Vue component props, they are not
+
+So this is a valid menu-placement customization:
+
+```js
+props: {
+  label: "Reports",
+  to: "/reports",
+  icon: "mdi-chart-box-outline"
+}
+```
+
+But if you later open the generated page file itself and add a Vuetify icon to the template, switch back to `@mdi/js`:
+
+```vue
+<script setup>
+import { mdiChartBoxOutline } from "@mdi/js";
+</script>
+
+<v-icon :icon="mdiChartBoxOutline" />
+```
+
+This split matters because JSKIT's shell menu components normalize menu metadata icons for you, while direct Vue icon props go straight to Vuetify.
+
+## What `page` is really good at
+
+The reason `page` is the primary subcommand is that it understands more than just "create this file".
+
+It also understands shell topology.
+
+If you create a page that lives under a parent page which has already been upgraded into a child-page host, `page` does **not** keep treating it as a top-level shell entry. It changes behavior and links the new page into the nearest host instead.
+
+That is what makes it fit naturally with the rest of JSKIT.
+
+### The important `page` overrides
+
+The happy path is intentionally simple, but `page` also has a small set of override options that matter as soon as you stop accepting the defaults.
+
+#### `--link-placement`
+
+Use this when the generated page link should go somewhere other than the generator's inferred default.
+
+Typical reasons:
+
+- you want the page in a different shell menu
+- you want the page link inside a specific existing outlet
+- you do not want the link to land in the normal top-level menu
+
+For example, if a page should appear in a settings menu rather than the shell drawer, `--link-placement` is the override that says so.
+
+#### `--link-component-token`
+
+Use this when the page link should render with a different link component than the default inferred one.
+
+In practice, this often means:
+
+- using a tab-style link instead of a normal menu link
+- using a local custom link token for a special shell section
+
+This matters most once you start targeting non-default outlets. A settings or tab host may want a different link renderer than the main shell drawer.
+
+#### `--link-to`
+
+Use this when you want to override the generated `props.to` value.
+
+This is especially useful for nested pages, because when JSKIT detects a parent subpages host it normally infers a relative link like:
+
+```js
+to: "./exports"
+```
+
+That default is usually correct. But if the host needs a different local target shape, or you are wiring a link into a custom outlet with different expectations, `--link-to` is the escape hatch.
+
+So the rough rule is:
+
+- if the link destination is obvious from the route tree, let JSKIT infer it
+- if you need a very specific link destination, use `--link-to`
+
+#### `--force`
+
+Use this only when the target page file already exists and you intentionally want to overwrite it.
+
+That is most common when:
+
+- you are regenerating an experimental page
+- you want to throw away the current file and replace it with fresh scaffold
+
+It is not a routing option. It is simply an overwrite guard.
+
+## Turning a page into a child-page host: `add-subpages`
+
+Suppose `Reports` should stop being a single screen and start becoming a section with child routes under it.
+
+Run:
+
+```bash
+npx jskit generate ui-generator add-subpages \
+  home/reports/index.vue \
+  --title "Reports" \
+  --subtitle "View and manage reporting modules."
+```
+
+This upgrades `src/pages/home/reports/index.vue` into a routed host page.
+
+On the first use in a fresh app, it also installs the support shell component:
+
+```text
+src/components/SectionContainerShell.vue
+```
+
+In the verified throwaway app, the command reported:
+
+```text
+Enabled subpages in src/pages/home/reports/index.vue for "/reports" using outlet target "reports:sub-pages".
+Touched files (2):
+- src/components/SectionContainerShell.vue
+- src/pages/home/reports/index.vue
+```
+
+After the command, the page gains three important pieces:
+
+- `SectionContainerShell`
+- a `ShellOutlet` for the child-page tabs
+- `RouterView`
+
+That means the page can now keep rendering shared content while child routes render underneath it.
+
+This is the first big distinction in this chapter:
+
+- a plain page is just a page
+- a subpages host is a page plus routed child-page structure
+
+If what you need is routed children, `add-subpages` is the right tool.
+
+### When `page` becomes a tab-like child instead of a top-level menu entry
+
+This is the key transition to understand.
+
+Before `add-subpages`, `page` usually creates:
+
+- a page file
+- a top-level shell link
+
+After `add-subpages`, that same `page` command may create:
+
+- a page file
+- a child link inside the nearest parent host outlet
+
+That is why nested pages often feel "tab-like" even though the generator command is still just `page`.
+
+The route page is still a normal page file. What changes is the inferred placement target:
+
+- no parent host found -> shell/menu entry
+- nearest parent host found -> child link inside that host
+
+So JSKIT is not switching to a different generator. It is switching the inferred placement behavior because the route tree now has a routed host above the new page.
+
+## Nested pages under an `index.vue` host
+
+Once `Reports` is a host, create a child page under it:
+
+```bash
+npx jskit generate ui-generator page \
+  home/reports/index/exports/index.vue \
+  --name "Exports"
+```
+
+This path shape matters.
+
+Because the parent host is:
+
+```text
+src/pages/home/reports/index.vue
+```
+
+the child belongs under:
+
+```text
+src/pages/home/reports/index/exports/index.vue
+```
+
+That `index/...` folder segment is not an odd JSKIT convention. It is the real nesting rule for children of an `index.vue` route host.
+
+And this is where `page` becomes interesting again.
+
+In the throwaway app, the command reported:
+
+```text
+Generated UI page "/reports/exports" at src/pages/home/reports/index/exports/index.vue.
+Touched files (2):
+- src/pages/home/reports/index/exports/index.vue
+- src/placement.js
+```
+
+But the placement it wrote was **not** another top-level shell link.
+
+Instead, it targeted the host outlet:
+
+```text
+reports:sub-pages
+```
+
+and used the tab-link renderer with:
+
+```js
+to: "./exports"
+```
+
+That is exactly the behavior you want:
+
+- `Reports` stays the host page
+- `Exports` becomes a child tab under it
+- the child route renders under the parent instead of becoming another top-level menu entry
+
+This is also why `--link-placement`, `--link-component-token`, and `--link-to` are often unnecessary in the default nested case. Once the host exists, JSKIT already knows the likely child placement target, link renderer, and relative `to` value.
+
+## Nested pages under a file-route host
+
+There is a second nesting shape that matters just as much.
+
+Create a dynamic file-route page:
+
+```bash
+npx jskit generate ui-generator page \
+  home/contacts/[contactId].vue \
+  --name "Contact"
+```
+
+Then upgrade that page into a host:
+
+```bash
+npx jskit generate ui-generator add-subpages \
+  home/contacts/[contactId].vue \
+  --title "Contact" \
+  --subtitle "View and manage this contact."
+```
+
+This time the parent is a file route, not an `index.vue` route.
+
+So the child-page path is different:
+
+```bash
+npx jskit generate ui-generator page \
+  home/contacts/[contactId]/notes/index.vue \
+  --name "Notes"
+```
+
+That is the other important nesting rule:
+
+- if the host is an `index.vue` page, children go under `index/...`
+- if the host is a file-route page, children go under that page's directory
+
+In the verified throwaway app, this command created:
+
+```text
+src/pages/home/contacts/[contactId]/notes/index.vue
+```
+
+and its link placement targeted:
+
+```text
+contacts-contact-id:sub-pages
+```
+
+So the exact host token changes, but the principle stays the same:
+
+- a nearer routed host changes where `page` places the new link
+- the child page becomes a tab or child link inside that host
+
+This is one of the most important things to understand about `ui-generator`: nested pages are not a separate feature bolted on afterwards. The generator already knows how to attach them to the right place.
+
+### A practical rule for child-page paths
+
+Use these two rules when deciding where the child page file should go:
+
+- host is `.../index.vue` -> child pages go under `.../index/...`
+- host is `...[param].vue` or another file route -> child pages go under `.../[param]/...`
+
+That is not only a file-layout preference. It is how the router keeps the parent host visible while the child page renders beneath it.
+
+## Adding small placed UI: `placed-element`
+
+Not everything should be a route.
+
+If what you need is a small block of UI rendered into an existing placement target, use `placed-element` instead:
+
+```bash
+npx jskit generate ui-generator placed-element \
+  --name "Alerts Widget"
+```
+
+In the verified throwaway app, that command touched:
+
+```text
+- packages/main/src/client/providers/MainClientProvider.js
+- src/components/AlertsWidgetElement.vue
+- src/placement.js
+```
+
+Those three edits explain the feature:
+
+- the component file is created in `src/components/`
+- the app's local client provider registers a new local token for it
+- `src/placement.js` adds a placement entry that renders that token
+
+This is different from `page` in a very important way:
+
+- `page` gives you a URL and a link
+- `placed-element` gives you a component token and a placement entry
+
+So if the thing you are adding should live *inside* an existing shell region, not at its own route, `placed-element` is the right command.
+
+By default, the element goes into:
+
+```text
+shell-layout:top-right
+```
+
+That is why this is such a good command for widgets, status panels, and compact shell extensions.
+
+### When `--surface` matters
+
+`placed-element` only needs `--surface` when JSKIT cannot infer the target surface cleanly.
+
+The easiest cases are:
+
+- the app has only one enabled surface
+- the chosen placement target clearly belongs to a page-owned outlet on one surface
+
+In those cases, surface inference is straightforward.
+
+The ambiguous cases are the ones to watch for:
+
+- the app has several enabled surfaces
+- the target placement is shared shell infrastructure rather than a page-owned outlet
+- the placement itself does not tell JSKIT which surface you meant
+
+That is exactly when `--surface` becomes important.
+
+A practical example is:
+
+```bash
+npx jskit generate ui-generator placed-element \
+  --name "Ops Panel" \
+  --surface admin \
+  --placement shell-layout:top-right
+```
+
+`shell-layout:top-right` can exist across several surfaces. If your app has several enabled surfaces, `--surface admin` tells JSKIT which one this element is actually meant for.
+
+So the rule of thumb is:
+
+- page-owned outlet target -> surface is often inferable
+- shared shell target in a multi-surface app -> pass `--surface`
+
+### `--placement`
+
+Use `--placement` when the default target `shell-layout:top-right` is not what you want.
+
+This is the option that answers:
+
+- *where should this element render?*
+
+In practice, it is the first override you will use for `placed-element`.
+
+### `--path`
+
+Use `--path` when the component file should live somewhere other than `src/components`.
+
+This is not about placement in the UI. It is about placement in the source tree.
+
+Typical reasons:
+
+- you want widgets under `src/widgets`
+- you want admin-specific pieces under a more specific component directory
+- you want support scaffold grouped near a feature area instead of dumped into the default component folder
+
+So `--path` changes where the new Vue file is written, not where it renders.
+
+### `--force`
+
+Use `--force` when the target component file already exists and you want to replace it with fresh generated scaffold.
+
+That is most useful when:
+
+- you are regenerating a throwaway prototype
+- you intentionally want to reset the file to generator output
+
+As with `page`, this is an overwrite guard, not a placement rule.
+
+## Adding a plain placement seam: `outlet`
+
+Now suppose you already have a component and you do **not** need routed child pages. You only need a named place where later UI can render.
+
+That is what `outlet` is for.
+
+In the verified throwaway app, after generating `Alerts Widget`, I ran:
+
+```bash
+npx jskit generate ui-generator outlet \
+  src/components/AlertsWidgetElement.vue \
+  --target alerts-widget:actions
+```
+
+That command touched only one file:
+
+```text
+src/components/AlertsWidgetElement.vue
+```
+
+and injected:
+
+```vue
+<ShellOutlet target="alerts-widget:actions" />
+```
+
+It did **not** add:
+
+- `RouterView`
+- `SectionContainerShell`
+- child-page tab structure
+
+That is the clean boundary between `outlet` and `add-subpages`.
+
+Use `outlet` when you want:
+
+- a placement seam inside an existing page or component
+- later content to be targetable there
+- no routed child-page behavior
+
+After adding the outlet, `npx jskit list-placements` showed the new target immediately:
+
+```text
+- alerts-widget:actions [src/components/AlertsWidgetElement.vue]
+```
+
+So `outlet` is the smallest possible way to make a Vue file part of the placement topology.
+
+### When `outlet` is the smaller correct tool
+
+This is the right command when you want to say:
+
+- "other things should be able to render here later"
+
+without also saying:
+
+- "this file should become a routed host page"
+
+That is why `outlet` is often the better choice for:
+
+- summary cards
+- header/action regions
+- detail panes
+- reusable components that need extension points
+
+If you do **not** need `RouterView` and you do **not** need child routes, `outlet` is usually the cleaner tool.
+
+### Choosing a good custom `--target`
+
+`--target` should be meaningful to humans, not just syntactically valid.
+
+A target like:
+
+```text
+customer-view:summary-actions
+```
+
+is good because it tells you:
+
+- the host area: `customer-view`
+- the position or outlet purpose: `summary-actions`
+
+That is much better than something vague like:
+
+```text
+custom-area:slot1
+```
+
+because the meaningful target name will later show up in:
+
+- `jskit list-placements`
+- placement entries
+- future generator commands
+
+So the target should describe the UI seam you are creating, not just satisfy the `host:position` format.
+
+## `add-subpages` versus `outlet`
+
+This is the distinction that most often causes hesitation.
+
+Use `add-subpages` when:
+
+- the page should stay visible while child routes render underneath it
+- you need a routed host page
+- you want later generated child pages to attach there automatically
+
+Use `outlet` when:
+
+- you only want a placement seam
+- the file already exists
+- you do not want routed children
+
+So:
+
+- `add-subpages` changes the routing shape of the page
+- `outlet` changes only the placement shape of the file
+
+`add-subpages` also tends to be the right tool when the parent page is meant to stay visible while a series of related child pages render under it. `outlet` is the right tool when the file just needs extension points.
+
+## Picking the right command
+
+The short rule is:
+
+- use `page` for new route pages
+- use `placed-element` for reusable placed UI
+- use `add-subpages` when the page should become a routed host
+- use `outlet` when you only need a placement target inside an existing file
+
+And the slightly longer rule is:
+
+- if it needs a URL, start from `page`
+- if it needs child routes, add `add-subpages`
+- if it does not need a URL but should render somewhere, use `placed-element`
+- if the file already exists and only needs a target for later UI, use `outlet`
+
+## Summary
+
+`ui-generator` is the non-CRUD side of JSKIT scaffolding.
+
+It writes app-owned UI structure in four different shapes:
+
+- route pages
+- placed components
+- routed host pages
+- plain placement seams
+
+The most important thing to remember is that nested pages are not a special afterthought. Once a page has been upgraded with `add-subpages`, later `page` generation automatically treats that host as the real placement target.
+
+That is why the commands fit together cleanly:
+
+- `page` creates routes
+- `add-subpages` turns routes into hosts
+- `page` can then create nested child routes under those hosts
+- `placed-element` and `outlet` handle the non-routed side of the same UI system
+
+Once the UI you want is no longer just page structure and starts needing real database-backed list/view/new/edit behavior, move to the CRUD generators chapter.

package/guide/agent/index.md

@@ -0,0 +1,39 @@
+<!-- Generated by `npm run agent-docs:build` from `docs/guide/index.md`. Do not edit manually. -->
+
+# Guide
+
+This guide is the main hands-on path through JSKIT.
+
+It starts with the smallest scaffold, then explains how to work with the JSKIT CLI itself before adding the shell and authentication. After that, it introduces the database-backed users layer, expands into console and workspace-aware app structure, and adds a small `App extras` section for optional runtime packages such as realtime and assistant. Finally, the guide breaks out generator-specific workflows into their own section.
+
+## Table of Contents
+
+### App Setup
+
+- [Initial Scaffolding](/guide/app-setup/initial-scaffolding)
+- [Working With The JSKIT CLI](/guide/app-setup/working-with-the-jskit-cli)
+- [A More Interesting Shell](/guide/app-setup/a-more-interesting-shell)
+- [Authentication](/guide/app-setup/authentication)
+- [Database Layer](/guide/app-setup/database-layer)
+- [Users](/guide/app-setup/users)
+- [Console](/guide/app-setup/console)
+- [Multi-homing](/guide/app-setup/multi-homing)
+
+### App Extras
+
+- [Realtime](/guide/app-extras/realtime)
+- [Assistant](/guide/app-extras/assistant)
+
+### Generators
+
+- [Intro](/guide/generators/intro)
+- [UI Generators](/guide/generators/ui-generators)
+- [CRUD Generators](/guide/generators/crud-generators)
+- [Advanced CRUDs](/guide/generators/advanced-cruds)
+
+## How to use this guide
+
+- Start with `App Setup` if you are building up a JSKIT app from scratch.
+- Use `App Extras` once the base app structure is in place and you want optional runtime packages.
+- Jump into `Generators` if you already understand the runtime packages and want app-owned scaffolding workflows.
+- Inside `Generators`, read `CRUD Generators` before `Advanced CRUDs`: the first chapter teaches the workflow, and the second explains the generated anatomy and customization points.