pomerado 0.1.2 → 0.2.0

package/dist/typescript/authoring/core/SKILL.md

@@ -23,248 +23,48 @@ against `typescript/src/runtime/index.ts` and show the real method signatures.
 
 ## Secret answers
 
-<!-- pomerado:hosted:start
-A `secret` answer comes back as a handle such as `{{secret.s1}}`, never the value,
-which you never see. In explore, test or `act` source, write the handle exactly as given as
-the whole string passed as the value to `fill`, `type` or `pressSequentially` on a `page`
-chain, or as a field of a `fetch` or `page.request` call to a literal URL on this site, inside
-the code of a `kernel.browsers.playwright.execute` call, such as
-`await page.getByLabel("Code").fill("{{secret.s1}}")`. The host fills in the value when it runs
-that source live and masks it in what comes back; offline targets get the handle unchanged.
-A handle anywhere else is refused before anything runs, naming its file and line: in a
-variable or a locator held in one, joined or transformed, returned, logged, in a URL or a JSON
-file, or beside code that reads the field back (`inputValue`, `evaluate`), reads its own source,
-or redefines JSON, a global, a prototype or a page or Kernel method; check the result in a later
-execute call. So is a handle the attempt never issued. An example and published
-source never hold a handle: a value the finished tool needs at run time is a declared
-`secret` question it asks with `ask` (caller-input skill).
-pomerado:hosted:end -->
+<!-- pomerado:section core.secret-answers:start
+A `secret` answer comes back as a handle such as `{{secret.s1}}`, never the value. Write the
+handle exactly as given as the whole string passed as the value to `fill`, `type` or
+`pressSequentially` on a `page` chain inside the code of a `kernel.browsers.playwright.execute`
+call, such as `await page.getByLabel("Code").fill("{{secret.s1}}")`. The host fills in the value
+when it runs that source live. Never hold a handle in a variable, transform, log, return or read
+it back, or put it in a URL or a file. An example and published source never hold a handle: a
+value the finished tool needs at run time is a declared `secret` question it asks with `ask`
+(caller-input skill).
+pomerado:section core.secret-answers:end -->
 
 ## Kernel scripts
 
-<!-- pomerado:hosted:start
-An operation is `defineOperation({ name, input, output }, async ({ kernel, sessionId,
-siteOrigin, siteDomain, input, decideDialog, ask, waitPastChallenge, verified, remainingMs, errors }) => ...)`. Its browser
-work is its own `kernel.browsers.playwright.execute(sessionId, { code, timeout_sec })`
-calls. Kernel runs each `code` string as plain Playwright code on its own `page` and
-answers `{ success, result, error, stderr }`. Throw
-`new errors.OperationFailure(String(answer.error), { stderr: answer.stderr })` when
-`success` is false or the page is not what the operation needs.
-pomerado:hosted:end -->
-
-<!-- pomerado:hosted:start
-- Make one execute call per operation. Add a call only at a `decideDialog` decision, an
-  `ask` for the caller's choice, after `waitPastChallenge`, where the flow could run past
-  300 s, or in a composed write, which keeps one call per `act` step.
-  `timeout_sec` is at most 300.
-- The code cannot see your variables. Write outside values into it with `JSON.stringify`,
-  and return plain JSON, never a Locator or Response.
-- Start a response wait in the same call as the click that causes it, with
-  `Promise.all([page.waitForResponse(...), button.click()])`. Listeners do not outlive a call.
-- Do site HTTP inside the page with `page.evaluate(() => fetch(...))`. Never use
-  `page.request` or a Node-side fetch, because the host records only page requests.
-- Patchright runs `page.evaluate` in an isolated world. To read the page's own JavaScript
-  variables, pass `false` as the fourth argument: `page.evaluate(fn, arg, undefined, false)`.
-- Console logs do not work. Return what you need to see.
-- When a challenge appears, call `await waitPastChallenge({ ready })`. `ready` is code that
-  returns true once the page is usable. It throws `ChallengeFailure` if the page stays blocked.
-- Never repeat a call that may have run.
-- When the site itself refuses a caller's value, such as a past date, an unknown airport code
-  or a party size over its limit, throw `new errors.InvalidInput(message)` saying why. `errors`
-  exists only in the script, never in a call's `code`, so when the page shows the refusal,
-  return a marker such as `{ refused: "why" }` from the call and throw once it returns. The
-  run then fails as the caller's input and nothing repairs the tool. A write that throws it
-  before entering a commit mark reports that it changed nothing. A page, control or response
-  that changed is still `OperationFailure`.
-- After a write, call `verified()` just before returning, once a call has read the saved
-  result back, or `verified({ confirmation: "message" })` when the site's own confirmation
-  for this submission proves it. Without it the write stays a possible effect. A write
-  declares which in its contract's `write`, and a write build runs as `act` steps; see
-  `writes/SKILL.md` and `forms/SKILL.md`.
-pomerado:hosted:end -->
+<!-- pomerado:section core.operation-shape -->
+
+<!-- pomerado:section core.execute-calls -->
 
 **The input schema.** Every caller sees the tool's input schema, so build it from the
 request and the flow, never from one caller's account or example.
 
-<!-- pomerado:hosted:start
-- The code works for every value the schema accepts. Never let the schema promise what
-  the code rejects, such as a string the code throws on unless it is the example's value.
-- Every value the code types, selects or fills on the site comes from the input and
-  accepts what the site's field accepts. An enum lists the site's full set of options,
-  never just the example's value. The example's values are one case, never limits.
-- Inputs are values a caller knows, such as codes, names, dates and counts, never a
-  suggestion's full display text or an internal id the caller cannot know. A closed list
-  of options stays an enum of the site's options, as above. When the options come from a
-  query, as in an autocomplete, typeahead or searchable combobox, the tool types the
-  caller's value and picks the matching suggestion itself: an exact code or name match
-  wins (an airport code picks that airport, not its city), and it throws `InvalidInput`
-  only when nothing matches or several match equally.
-- On a write, every choice the session met is an input: each option on the path,
-  add-ons and pre-selected defaults included. Make it required when the site requires
-  a choice (a fare class) and optional when it does not (a seat). An unset optional input
-  keeps the page's default; an add-on, a pre-selected paid option or a saved payment is
-  never left to a default, so ask about it (the writes skill).
-- Never make an account-specific value (a passenger, loyalty number, saved card or
-  address, account or member ID) an enum member, example or default in a public
-  schema. Take it as a free-form input.
-- The host's `businessInputTypes` is a value-free tree of the JSON types in the caller's
-  input. Use it to pick compatible types when a credential in the input is masked; a mask
-  does not mean the value was a string. It says nothing about
-  required fields, array lengths, numeric bounds or future values: derive those from
-  the request and reviewed evidence.
-- Never hard-code a value the caller could vary: it comes from the input, never a literal
-  in source, a schema default or the definition. A good tool exposes the options its
-  purpose calls for, not only the ones the request names: record every optional field the
-  flow offers that bears on the tool's purpose as an optional input wired to its control,
-  such as cabin class (economy or first) on a flight search, even when the request never
-  mentions it. Leave out controls unrelated to the purpose, such as a language switch or a
-  newsletter opt-in on a search. Record such a field as an optional input whether or not
-  you ask about it, since callers of the tool can set it. Ask about one the input leaves
-  open only when the request's purpose clearly depends on its value, in the same batch as
-  your other questions; leave the rest unset, keeping the page's default.
-- When a read's caller input is empty (`{}`), write the example's input from the request
-  and the owner's answers, with dates normalized (10/4 is the next October 4, as
-  `2026-10-04`), and pass it as `exampleInput` on the example's execute. Make each of its
-  keys a schema input; publication returns a key the schema lacks as an `example_input`
-  input feedback.
-- Callers and Guardian see the JSON Schema form, so write every constraint in one it
-  shows: a `Schema.filter` shows nothing, its description included, so use
-  `Schema.NonEmptyString`, `pattern`, `minLength`, `Int`, `between` or `Literal`. Type every
-  output field, never `Schema.Unknown`. A read publishes the schemas in its current source,
-  and its example's own input and output must decode under them, so settle both before that
-  example.
-- Give every input and output field, nested object and array item fields included, a short
-  `description` annotation saying what it is, with the unit or format where one applies:
-  "Departure airport as a three-letter IATA code", "Departure date, YYYY-MM-DD". Effect's
-  stock text, such as "a non empty string", is no description. Annotate the field's own
-  schema, inside `Schema.optional(...)` for an optional one; a `Schema.Date` keeps it only on
-  `Schema.optional(Schema.Date)` or `Schema.propertySignature(Schema.Date)`. Callers see each
-  beside its name.
-- Shape inputs and outputs like Pomerado's own API, so every tool reads alike: field names in
-  snake_case; dates as `YYYY-MM-DD` and timestamps as ISO 8601 with an offset; money as an
-  integer in minor units with an ISO 4217 `currency` beside it, such as `total_minor` 12999 and
-  `currency` `"USD"`; enum values in lowercase snake_case (`"premium_economy"`); booleans named
-  as statements (`refundable`, not `is_refundable_flag`); lists named in the plural; and the
-  unit in the field name or its description (`duration_minutes`). Convert between these and the
-  site's own formats in code.
-- Give every input field one `examples` annotation value, which callers, the docs and the Try it
-  form use to assemble a sample request: public, generic data such as a well-known airport code
-  (`examples: ["SFO"]`), a date a few weeks ahead or a common product category. Never use a value
-  from this session: not the caller's input, the owner's answers or anything the site showed
-  this account.
-- Descriptions, titles, examples and defaults are published and reviewed for private data,
-  and an annotation never declares its contents public. Explain constraints without copying private input
-  or unneeded numeric identifiers; for a nonnegative safe integer,
-  `Schema.between(0, Number.MAX_SAFE_INTEGER, { title: "Safe integer", description:
-"Nonnegative safe integer amount" })` keeps the bound with public prose. Return a
-  supplied currency value from the validated input instead of embedding it in source.
-  Only host-approved standard enums and origins are recognized as public.
-- Guardian's publication review checks the schema and the code that fills it. A
-  `not_published` result with reason `input_feedback` lists `account_specific_enum`,
-  `input_option` and `example_value` findings. They are feedback, on a read or a write:
-  correct the source (make the value free-form, add the option as an input, or widen the
-  input and the code that sets it) and call `finish_build` again with the same
-  `executionId`. The host reads the schemas offline from current source and checks that the
-  example's or session's own input, and a read example's output, still decode. Never run a
-  write again for it. After two such rounds, or if you stop
-  without fixing them, the host publishes the last reviewed version privately to the
-  caller's account and flags it.
-pomerado:hosted:end -->
+<!-- pomerado:section core.schema-coverage -->
+
+Typed output, where the site makes it easy:
+- Prefer numbers for prices, amounts and counts, with the currency or unit in its own field.
+- Prefer ISO 8601 for dates and times, and minutes for durations.
+- Keep one field per fact. Split a combined line into separate fields.
+- If a value does not parse cleanly, returning the site's own text is fine.
 
 **Search results.** When the site says how its results matched, such as exact matches
 against suggested or fallback items, a search tool returns that. Otherwise its description
 and output say plainly that results may include the site's own suggestions.
 
-<!-- pomerado:hosted:start
-The host owns input/output validation, deadlines, account binding, the browser,
-capture and screened logs. Do not close the page.
-
-pomerado:hosted:end --><!-- pomerado:standalone:start
+<!-- pomerado:section core.host-ownership:start
 
 The host owns input/output validation, deadlines, caller authority and the browser. Do not close the page.
 
-pomerado:standalone:end -->A newly allocated Page may start at `about:blank`; the supplied site origin does
+pomerado:section core.host-ownership:end -->A newly allocated Page may start at `about:blank`; the supplied site origin does
 not mean the host has navigated there. Navigate to the authorized site and wait
 for a named page condition before inspecting its title or controls. Empty content
 on a blank Page is not evidence about the website or its availability.
 
-<!-- pomerado:hosted:start
-Take the site origin from the context's `siteOrigin`. If it is undefined, fail before
-live navigation; offline fixtures intentionally have no live origin. Build URLs with
-`new URL("/", siteOrigin).href` or an observed relative path and write them into the
-code. Never embed the site's hostname or account-specific origin as a literal in
-authored source, schema examples, or logs, and never replace it with `page.url()`
-after a redirect. The host supplies the primary origin even when the model cannot see
-it. This value does not authorize other destinations or credential submission.
-The context's `siteDomain` is the site's registrable domain, which the host computed with
-the public suffix list: a page is on the site when it is `https:` and its hostname is
-`siteDomain` or ends with `"." + siteDomain`, and only `siteOrigin` itself is the site when
-`siteDomain` is undefined. Write it into the code as you do `siteOrigin`, and never derive it
-from the hostname: its last labels can be a public suffix (`co.uk`) or another tenant's
-(`github.io`). `references/native-page.ts` shows the check. Use `page.evaluate`,
-`locator.evaluate` or `locator.evaluateAll` when code needs browser globals such as
-`document`.
-For visible page text, prefer a scoped locator's `innerText`; `textContent` also
-includes hidden text and script/style contents. Read embedded data separately
-when it is relevant to the requested operation.
-Default budgets: action, readiness and navigation 30 s. Give every Playwright
-wait in the code an explicit `timeout`, and keep `timeout_sec` within `remainingMs()`.
-Child waits cannot extend the outer deadline. Explicitly name observation conditions.
-`domcontentloaded` is document readiness, not readiness of the requested page or
-control. Initial navigation can land on a temporary verification page before the
-site redirects or renders its controls. JavaScript challenges, redirects and
-delayed rendering can be intermittent: a fast exploration load does not establish
-that later executions will be immediately ready. Include a bounded wait for the
-expected page or control even when exploration never observed a delay. Derive
-that readiness condition from the intended page, not from having seen a particular
-challenge. Wait for a unique operation control or page state before testing absence
-or choosing a fallback. Use `locator.waitFor` or a bounded polling loop;
-`count()` and `isVisible()` only observe the current instant. A ready page should
-pass immediately; do not add a fixed sleep. Share one bounded navigation deadline across navigation
-and first-page readiness, as in `references/navigation.ts`. Readiness polling
-only observes: do not repeat `goto`, reload, login, submission or another action
-inside it. Preserve site/path and account guards while waiting.
-After an action that can navigate, wait for the observed destination URL when known,
-then a specific destination control or page state before extracting. Keep the action,
-readiness wait and extraction in the same Kernel execute call when possible. If a read
-reports “Execution context was destroyed,” the action may already have succeeded.
-Reacquire page/frame locators, wait for readiness and retry only the read within the
-original deadline. Never repeat the click or submission as part of that recovery.
-Use observed conditions, without fixed sleeps or whole-page network-idle waits.
-For an unknown destination, inspect after the document transition; do not invent a
-selector or repeat the action in a follow-up read.
-Hosted Kernel browsers already use stealth's automatic solver for supported
-challenges, including with the assigned proxy. Observing a challenge
-does not establish that the solver failed or that human input is required.
-After a probe reveals a challenge, inspect the retained Page in follow-up probes
-and wait for the intended page/control within the existing deadline and job budget;
-do not click the challenge, reload, or navigate to another route merely because
-the earlier probe timed out. A new probe execution does not require new navigation.
-A live example, a live read `test`, and a write session's first `act` step are
-different: the host resets
-the browser to the site origin before it runs,
-and clears exploration cookies and site storage. A signed-in build gets back the session
-saved right after sign-in instead, so a stale session shows up as a login wall that a new
-sign-in fixes. That source must perform the flow from its input,
-never rely on a page an exploration left open. So a read iterates from a clean start,
-and re-running its example or live test is normal. A live test stays read-only. A write
-session's later `act` steps continue on the page the previous step left.
-If the deadline expires, report the named readiness failure and use current
-screened evidence to distinguish a remaining challenge, loading and changed
-layout. The `captcha` skill covers the on-demand `captcha_state` check, the shared
-wait budget and `waitPastChallenge`, which operation code calls instead of
-raising `ChallengeFailure` itself. Do not invent a CAPTCHA bypass or replace the target with an arbitrary
-first element. Resolve role and computed accessible name from observed evidence;
-`searchbox` and `textbox`, and their exact names, are not interchangeable.
-When a Playwright timeout names a locator, repair that wait and keep the checks that
-already passed. A `DeadlineExceeded` phase of `execution` is the shared operation
-deadline. Before increasing a timeout, make one bounded observation of the candidate
-target count or state; increase it only when evidence shows that the correct unique
-target is slow. Do not catch-and-repeat timed-out work. A click or navigation that
-timed out is an uncertain transition: it may already have taken effect. Inspect the
-retained page in the next probe and do not repeat the action until you know where
-the page landed.
-pomerado:hosted:end -->
+<!-- pomerado:section core.site-origin -->
 
 Never call `.first()` (or `.nth(0)`) on a broad text or regex match, whether to
 click it or to wait for readiness: collapsed menus often hold an earlier hidden
@@ -295,14 +95,10 @@ it. Bounded repeatable reads and transient search interactions may continue unde
 existing authority when source and current observations establish their semantics;
 inspect state before choosing a retry or safe read reconstruction. A search/query
 submission can be a read; autosave, drafts, uploads, holds and business commitments
-are writes regardless of method or control names. <!-- pomerado:hosted:start
-Raw Page calls require host review,
-capture and isolation; required services are dependencies, not permissions.
-
-pomerado:hosted:end --><!-- pomerado:standalone:start
+are writes regardless of method or control names. <!-- pomerado:section core.raw-page-calls:start
 Raw Page calls require host review and caller authority.
 
-pomerado:standalone:end -->Preserve the host's reported failure stage and dispatch state. Missing output or
+pomerado:section core.raw-page-calls:end -->Preserve the host's reported failure stage and dispatch state. Missing output or
 a provider 404 does not prove that navigation, login or a previous action never
 happened. A guard failure before one click says nothing about earlier actions in
 that script. For a reviewed current-state inspection, check that the page is on the
@@ -315,38 +111,11 @@ because a later extraction call timed out.
 Never recreate a write or login to recover an observation. See
 `references/native-page.ts` for a site-guarded read.
 
-<!-- pomerado:hosted:start
-The tools and the files you may edit are in `AGENTS.md`. The host binds the caller's actual input/account; no tool
-argument selects another account or private reference. A live read test's `testInput` is
-the one input you choose, with public values only (.agents/testing/SKILL.md). Every new
-command/probe/execution gets Guardian review, including maintenance residual work.
-Nested Playwright actions do not each trigger review. A probe operation still receives the host-bound business
-input. Its declared schema must accept that input even when the bounded observation
-does not use every field; do not replace it with an empty or probe-only schema.
-pomerado:hosted:end -->
-
-<!-- pomerado:hosted:start
-For captured parser checks, use the host's `savedHTTP` or `savedDOM` execute target
-with published capture paths in `fixtureRefs`. The testing skill explains the
-replayed HTTP service and the saved page. A `savedDOM` test runs only a Kernel
-script. The host owns fixture binding, offline Chromium, routes and cleanup. These
-checks retain original business input but do not sign in, count as a read's proving
-example or perform a write.
-pomerado:hosted:end -->
-
-<!-- pomerado:hosted:start
-Choose relevant references: writes, testing, pagination, variants/recovery, forms,
-HTTP/MCP, caller input for a choice only the page can offer, or a code, during the
-run, and publication before the first `finish_build`. Read their bodies only when useful.
-Finish with actual execution evidence and
-truthful coverage through `finish_build`. A write finishes after its session's
-confirmation read; never run the composed script live. Ask only as "Try hard, then
-ask" allows. If infrastructure prevents further
-work, report the recorded failure and unresolved effects, then end without
-publication; the host preserves an incomplete build. Do not ask the user to
-answer a provider outage. Publishing future code does not replace the build's own
-result or resolve uncertain effects.
-pomerado:hosted:end -->
+<!-- pomerado:section core.tools-and-files -->
+
+<!-- pomerado:section core.captured-checks -->
+
+<!-- pomerado:section core.references -->
 
 Examples: `references/parser.ts`, `references/native-page.ts`,
 and `references/selection.ts`. For custom choices, the forms skill includes
@@ -365,16 +134,7 @@ Loading is not proof of a new version. An identity mismatch blocks every candida
 
 See the compiling `references/variants.ts` example.
 
-<!-- pomerado:hosted:start
-Use screened old/new captures and report tests of the guards against known layouts,
-ambiguous/unsupported/loading states and varied private inputs. Describe missing
-coverage honestly; the host associates its actual capture paths and test receipts
-privately with the published revision. A receipt records execution, not a claim
-that every declared variant was tested. Public bundles must exclude private fixtures.
-There is no fixed test count. Existing enabled variants cannot be silently omitted
-by a future publication. Explicit disable or a new validated publication affects
-future calls; a selected variant failure never restarts an old write script.
-pomerado:hosted:end -->
+<!-- pomerado:section core.layout-captures -->
 
 ## Authenticated operations
 
@@ -391,41 +151,11 @@ reach the credential form from that entry. A URL no sign-in can start from, and
 a failed sign-in, come back with the reason and the next step; fix the cause and call
 authenticate again. Do not author a login-routing metadata file.
 
-<!-- pomerado:hosted:start
-Inspect login markup using reviewed read-only `explore` without private credential
-injection. Use execute purpose `authenticate`, target `liveBrowser`, to sign in. The
-host runs the explicit direct HTTP request or the observed `signInStep` and reports the sign-in. It runs no
-generated code, and it does not claim or execute the business example. Login effects
-have separate authentication evidence. If the same browser still shows a login page or
-a signed-out state afterwards, inspect the page and correct the recorded steps or report the failure.
-Credentials the site rejected are never resubmitted. After a browser recovery gives a
-new, empty profile, its notice says the signed-in session ended: submit `authenticate`
-again. The host signs in on each fresh profile, at most three times per attempt, and
-the notice says when that allowance is spent. Wait for the
-signed-in page to become ready after login. Disappearance of the login form alone is
-insufficient. The host requests codes and choices through protected input requests during
-`authenticate`.
-pomerado:hosted:end -->
-
-<!-- pomerado:hosted:start
-Only the host requests website credentials, and only during `authenticate`.
-When the invocation has no login yet, that `authenticate` uses the site's saved
-login when this build may use it, otherwise asks the caller for one, and signs in
-within the same call; a confirmed login rejection is corrected the same way, once.
-`request_input` cannot request credentials. If the site cannot be reached, report that instead
-of starting sign-in. Never request durable credentials in model arguments or
-history. With `save: false`, each NEW invocation needs a login
-of its own: username and password, or a username alone for a passwordless site
-(the host asks for a code when the observed autofill screen needs one); an existing profile alone
-cannot substitute for it.
-Saving credentials is separately authorized and does not change a successful
-website action into a reason to execute it again.
-pomerado:hosted:end -->
-
-<!-- pomerado:hosted:start
-For capture evidence, `README.md` lists `reference/captures.md`: what the index holds, pending
-screening and reading large files in parts.
-pomerado:hosted:end -->
+<!-- pomerado:section core.login-markup -->
+
+<!-- pomerado:section core.credentials -->
+
+<!-- pomerado:section core.capture-evidence -->
 
 Keep exploratory output focused on the current question: the relevant control or
 container, its state, and the nearby choices. Prefer the existing accessibility
@@ -477,29 +207,9 @@ host's own entry-page load. The mint continued past each listed gap.
 
 `hostIncidents` kinds:
 
-<!-- pomerado:hosted:start
-- `observation_gap`: the host may have missed some of the browser's requests for a while, so
-  that execution's effect is possible.
-- `capture_unavailable`: no screened capture exists for that execution, even after
-  a retry, or for the last moments of a browser the host replaced. The build continues:
-  use its result and events, and name the gap in `finish_build` coverage. Publication
-  does not depend on background capture unless a publication response says so.
-- `dialog`: the host settled a page dialog itself. An expired or unobservable
-  dialog was dismissed; an uncertain resolution leaves the effect possible.
-- `proxy_swap`: the host moved the browser to another outbound proxy. A request in
-  flight at that moment may have failed, so treat it as possibly sent.
-pomerado:hosted:end -->
-
-<!-- pomerado:hosted:start
-Unclear means possible. `websiteEffect: may_have_dispatched` makes that execution's
-effect possible: reconcile current state before claiming success, and never repeat
-a claimed example or an uncertain write blindly: in a write session or a maintenance
-repair, read back whether the write happened first, and do the write only if it did not.
-`hostBug: true` marks a suspected Pomerado defect, which the host has reported. On a
-`dialog` or `observation_gap`, report it in your diagnostics and do not work around it;
-on `capture_unavailable`, keep building.
-
-pomerado:hosted:end --><!-- pomerado:standalone:start
+<!-- pomerado:section core.incident-kinds -->
+
+<!-- pomerado:section core.completion:start
 
 ## Standalone execution and completion
 
@@ -511,4 +221,4 @@ Declare explicit input and output schemas, concrete types and bounds for each su
 
 Only the host asks for website credentials and only during `authenticate`. Give it the observed field selectors, slots, allowed identifier kinds, format and submit. No generated source receives the raw password; follow the same destination, stale field/focus, no-readback and code-handle rules as hosted execution. Correct a refused binding by reading the current screen. A rejected credential needs caller correction; do not resubmit it.
 
-pomerado:standalone:end -->
+pomerado:section core.completion:end -->

package/dist/typescript/authoring/forms/SKILL.md

@@ -18,48 +18,7 @@ verified query. For an in-page update, wait for evidence that the new query has
 completed. An immediate snapshot with an empty title and missing controls can be
 a transition observation; it does not establish an empty business result.
 
-<!-- pomerado:hosted:start
-Derive `getByRole` names from a scoped `locator.ariaSnapshot()` or a retained ARIA
-snapshot. `getAttribute("aria-label")` reads only that DOM attribute, not the
-computed accessible name. The name may exist when the attribute is absent because
-it comes from text, labels or `aria-labelledby`. Read the snapshot or use an
-observed `getByRole` name; an `aria-label || innerText` fallback does not compute it.
-Use the observed role/name to build native locators and check their count,
-visibility and current value. Do not make exact indentation or adjacency in a
-whole-page ARIA snapshot a prerequisite for using an otherwise verified control.
-Snapshots describe a tree whose nesting and extra siblings can change. If a
-locator is missing or ambiguous, inspect its relevant scope and report what was
-observed before changing the locator. Use `inputValue()` on that same verified
-input for query readback instead of reconstructing its accessible name from DOM
-attributes inside a separate `evaluate` call.
-One broad body or main snapshot can be useful for initial orientation. When that
-snapshot has already succeeded, reuse it for related reads. If broad snapshot work
-is measured slow or times out during repeated-result extraction, prefer the
-established local result container or item locators instead of recomputing the
-whole subtree. CSS `locator("main")` matches a literal `main` element, while
-`getByRole("main")` matches the computed accessible role. When retained evidence
-does not establish which structure exists, compare their finite counts once under
-a bounded call, require the intended scope to be unique, then use that scope.
-Do this before changing timeouts. ARIA snapshots are multiline structured text;
-do not use a greedy cross-line capture for one quoted accessible name. Keep parsing
-bounded to the intended record, handle quoted escapes, and fail explicitly when
-the observed record does not match the established grammar.
-Keep the control's label, current value and selected state as separate observations.
-Use `inputValue()` for an input's current value; a nonempty label must not hide it.
-Treat counts as presentation text: support the site's observed singular and plural
-forms, and allow an owned menu option's computed accessible name to include an
-observed count suffix. Scope the option lookup to that menu and match only the
-established suffix grammar; do not require an exact raw `aria-label`.
-During exploration, read the selected state after the action to establish how this
-control commits a choice. For dates, establish the committed day, month and year
-from the control and its owned calendar state; a navigation URL, field label or
-requested input alone does not prove that the application accepted the date. In
-published code, keep a committed-state check when selection is the operation's
-final result or the next action needs that value. Do not turn every selection in a
-larger flow into an intermediate success assertion; the read-back before returning
-(`AGENTS.md`) checks each input the page shows. Reuse the current authorized
-page for missing observations instead of restarting a completed search.
-pomerado:hosted:end -->
+<!-- pomerado:section forms.role-names -->
 
 A committed selection can change a control's accessible name. During exploration,
 reinspect its owned container to learn the committed state. If a later action needs
@@ -110,16 +69,7 @@ picker into a larger flow, establish its popup ownership and fresh-query signal
 choose the right option; read the committed state during exploration, when the next
 action needs it, or as part of validating the requested final outcome.
 
-<!-- pomerado:hosted:start
-Preserve add/replace and single/multiple intent. Query aliases
-are alternate searches for one stable choice, not extra selections. Demonstrate
-portal ownership, query-generation freshness and complete/windowed option coverage;
-virtualized options require bounded traversal with stable keys. An ambiguous choice
-needs a resolver or a `request_input` question, as `AGENTS.md`'s "Try hard, then
-ask" says; take the site's default only when the choice is not a write and is easy
-to reverse, and list it in `finish_build` `assumptions`. Do not claim uncaptured
-options do not exist.
-pomerado:hosted:end -->
+<!-- pomerado:section forms.selection-intent -->
 
 Playwright `locator.count()` and `locator.isVisible()` are immediate observations,
 not waits. After opening a popup, wait for its owned, named container and requested
@@ -147,30 +97,9 @@ field change, file upload or draft creation may already be a website write.
 
 ## Multi-step forms
 
-<!-- pomerado:hosted:start
-Filling in or advancing a form that saves data on the site (an application, a profile,
-a contracting or checkout form) is a write, even when nothing is submitted yet: many
-such forms save each step as you go. A read build may not fill in or advance such a
-form (it asks for a write upgrade first, as the writes skill says); a write build does the whole form as its one task. A search, filter or query form
-whose read semantics are established stays a read.
-pomerado:hosted:end -->
-
-<!-- pomerado:hosted:start
-- Walk every step for real, in the session, with the caller's values. Never infer a
-  later step's fields, options or wording in place of reaching it; the page after
-  "Continue" is evidence only once you are on it.
-- Before the first `act` step, read what is already visible on the page, and read the
-  page's own scripts or captured responses that describe the form (field lists,
-  validation rules, step definitions) to anticipate what later steps ask. Use that to
-  ask for the values up front, in one `request_input`, for every field you can see or
-  anticipate that the input does not settle.
-- A step that asks for something you could not anticipate is asked in place when you
-  reach it, with `request_input` during the session, or as a declared `ask` in the
-  next step's script for a choice that exists only on that page. Check the page again
-  after the answer.
-- A step the site saved stays saved. If a step fails, read the page before running it
-  again; redo it only when it did not finish.
-pomerado:hosted:end -->
+<!-- pomerado:section forms.saved-steps -->
+
+<!-- pomerado:section forms.step-rules -->
 
 Expose prerequisite resolvers for valid choices. A prepare/confirm flow binds the
 draft to the account and requires caller-expected item, quantity, amount/currency
@@ -195,10 +124,10 @@ describes. Without it the write stays a possible effect. Never call it for a toa
 a status code alone or a missing confirmation, and make no execute call after it: a
 later call makes the effect possible again. Missing confirmation preserves uncertainty; it
 does not authorize another submit.
-<!-- pomerado:standalone:start
+<!-- pomerado:section forms.fixture-checks:start
 
 ## Standalone fixture checks
 
 Use the same supplied-input/observed-control rules and browser helper APIs. Check pure parsers with `pureFiles` and supplied fixtures; verify actual interaction and final state with bounded `liveBrowser` steps. Never invent a live field value merely to test a control.
 
-pomerado:standalone:end -->
+pomerado:section forms.fixture-checks:end -->

package/dist/typescript/authoring/pagination/SKILL.md

@@ -9,35 +9,18 @@ A cursor represents the query and a logical position under the same authorized
 tenant/account/site. The host protects and validates that scope; a saved profile
 or an agent's remembered Page is not a cursor authenticity check.
 
-<!-- pomerado:hosted:start
-1. Validate cursor/query/account scope before browser effects.
-2. Inspect restored live/profile state. Reuse it only if the current signed-in page,
-   query and logical position are suitable.
-3. Otherwise start from the host's fresh sign-in and reconstruct the
-   repeatable read/search, then advance to the logical position. Loading a profile
-   does not restore JS heaps, expiring server cursors, drafts or DOM state.
-4. Tolerate changing live data. Return observed IDs and coverage; do not promise an
-   immutable snapshot if the site has none. Prefer stable IDs over visual row index.
-5. If reconstruction is unsupported, return bounded partial data with an explicit
-   reason and no pretend next cursor.
-pomerado:hosted:end -->
-
-<!-- pomerado:hosted:start
-Never recreate a hold, draft, upload, payment token or write as pagination. Unknown
-prior effects require recovery, not fresh navigation. A mint question keeps the live
-browser for up to 10 minutes; that is not cursor expiry. Profile load/save failure
-or 24h inactivity expiry selects fresh reconstruction where supported; it does not
-invalidate an otherwise meaningful read cursor.
-pomerado:hosted:end -->
+<!-- pomerado:section pagination.continuation -->
+
+<!-- pomerado:section pagination.no-recreated-writes -->
 
 Use and test both warm and fresh paths, including expired state, changed live data,
 wrong query/account and unsupported reconstruction. `references/pagination.ts`
 provides a compiling authoring pattern; its hooks are site logic, not platform
 authentication or a universal pagination engine.
-<!-- pomerado:standalone:start
+<!-- pomerado:section pagination.cursor-scope:start
 
 ## Standalone cursor scope
 
 A logical cursor is not proof of browser or account identity. Validate its supplied query and scope before effects, verify the current page and account context, and reconstruct only a repeatable read when the evidence supports it. Never recreate a write to recover a cursor.
 
-pomerado:standalone:end -->
+pomerado:section pagination.cursor-scope:end -->