Skip to main content

Getting started

You just registered a domain in Appilot. This page is the Day 1 checklist: the order in which to author content so the agent becomes useful as fast as possible, without falling into the over-configuration trap.

If you have not yet read Authoring for the agent, do that first. This page is the checklist; that page is the mental model. The two are designed to be read together.

What "useful" looks like at the end of Day 1​

By the end of this page, an end user on your domain should be able to:

  • Ask "what does this app do?" and get a grounded answer.
  • Ask "how do I do X?" for the 2–3 most common workflows in your app and get a usable Action Plan.
  • Get an honest 🔴 ("I don't have guidance for this") on a question you have not authored yet, with the question logged to your Missing Knowledge inbox.

You are NOT trying to cover every workflow on Day 1. You are establishing the spine.

The checklist (read top to bottom, in order)​

Step 1 · Register the domain (5 minutes)​

Done already if you are reading this. If not, see Domain configuration.

Verification: the domain appears in your Backoffice with status "Registered", and an end user with the extension installed sees the Appilot panel open on that domain.

Identity (only if you embed the widget). If your users access Appilot through the embeddable widget, decide how they authenticate: the common case is widget integration via your own app (your developers generate a widget key + server secret, see Widget keys and Widget Installation → Connecting your users), and organizations with a corporate IdP can use Enterprise SSO. On Day 1 you can skip this and sign in manually to test; circle back once you have real users.

Step 2 · Ingest your existing documentation (15–60 minutes)​

Most organisations already have something: a user manual PDF, a Confluence export, internal training docs. Upload those to RAG files before authoring anything by hand. The RAG store is the cheap-to-build long-tail; your hand-authored Knowledge is the curated spine.

  • Upload PDFs / Markdown via Knowledge → Import from PDF or the RAG files page.
  • Let the import finish; review extracted entries before publishing.
  • Discard low-quality extractions; you can always re-import later.

Verification: open the Test Chat (top-right of Backoffice for this domain). Ask a question that should be in the uploaded material. You should get a 🟡 response that cites the document.

You can skip this step if you have no existing documentation; you just start more slowly.

Step 3 · Pick your 3–5 "spine" workflows (10 minutes)​

A "spine" workflow is a procedure most of your users will perform regularly. Examples for different industries:

  • E-commerce admin app: "create a product", "fulfil an order", "issue a refund".
  • Public-service portal: "create a digital service", "configure mandatory parameters", "publish a draft".
  • HR app: "add a new hire", "approve a leave request", "run payroll".

Don't pick more than five. Don't pick anything obscure. The spine carries the rest.

Step 4 · Author one Knowledge entry per spine workflow (30–90 minutes)​

For each spine workflow, write a single Knowledge entry of about 200–500 tokens (~150–400 words):

  • Title: a noun phrase. "Product creation", not "How to create a product".
  • Scope: page if the workflow lives on specific Views; domain_global only if it is genuinely cross-page.
  • Body: explain the why — the rationale, the ordering, the conformance rules. Do NOT re-describe what's on the screen.
  • Reference any Forms / Controls / Tools you plan to author later via inline tokens ({{form:online-service-form}}, {{control:action-save}}). The Backoffice will warn when a token references something that doesn't exist yet; that's fine for now.

Keep your domain_global set under 4–8 entries total. These load on every turn; treat them like gold.

If your existing documentation already had a good narrative for one of these workflows, you can lift it directly from RAG and refine. If it didn't, write fresh.

Verification: open the Test Chat. Ask the user-facing question your workflow answers. You should now get a 🟢 or 🟡 response that quotes your wording. The Action Plan will be empty for now — that's expected, you haven't authored Forms yet.

Step 5 · Test the spine end-to-end (10 minutes)​

For each workflow, ask a real user-style question in the Test Chat. Note where the answer is:

  • Correct → leave it alone. The assistant doesn't need Forms or Controls here yet.
  • Correct but not actionable ("the assistant explained it but didn't help me do it") → candidate for a Form or Control in Step 7.
  • Wrong → fix the Knowledge entry; do not jump to authoring Controls.
  • 🔴 ("no guidance") → the workflow needs a new Knowledge entry, not a Control.

Step 6 · Verify View detection works for the spine pages (10 minutes)​

Open the page where each spine workflow lives. Confirm the Backoffice's Views tab shows the right View as "Last detected" recently. If your app is a SPA where the URL doesn't change, you may need a DOM detection rule. See Managing Views.

If View detection is wrong, your page-scoped Knowledge won't load when users get to that page, and the agent will fall back to less precise context. Fix this before continuing.

Step 7 · Add Forms / Controls / Tools only where the spine needs them (optional, hours-to-days)​

This is where most teams over-configure. Resist.

Open the AI Reports for your spine workflows after some test usage. For each workflow:

  • Did the agent narrate a step correctly but fail to do it? Candidate for a Form (multi-field workflow) or a Control (single button). Author with the 4-bullet rule from Authoring for the agent.
  • Did the agent give an answer but obviously lacked a server-side fact (a lookup, a calculation)? Candidate for a Tool. See Managing Tools.
  • Did the agent point at "the sidebar" or "the notifications area" vaguely? Candidate for a Zone. See Managing Zones.
  • Did the agent answer correctly? Author nothing else.

Author one entity at a time, test in the Test Chat, then move on. Do not batch-author 30 Controls because they "might" be needed.

Step 8 · Wire the iteration loop (5 minutes, then ongoing)​

The agent is now spine-complete for the workflows you picked. The remaining gaps will come from real users, not from your imagination. Wire the loop:

  • Missing Knowledge inbox (Requests management): every 🔴 response is logged here. Triage weekly.
  • AI Reports (Analytics): browse 👎 conversations to find systemic gaps.
  • Coverage policies (Coverage policies): if you want to enforce a minimum coverage level per domain.

You are done with Day 1.

What NOT to do on Day 1​

The single most common mistake new admins make is trying to author everything before launching. Symptoms of this failure mode:

  • 50+ Controls authored for an app with 20 meaningful affordances.
  • domain_global Knowledge set over 4,000 tokens, covering "everything important".
  • Three Forms per workflow because "maybe the user wants the short version".
  • Tools authored for facts (get-mandatory-parameters returning a static list — that's a Knowledge entry).
  • No test chat usage; configuration shipped untested.

The agent's accuracy degrades faster from over-authoring than under-authoring. Start small. Add only when AI Reports tell you to.

The flip side — Day 1 under-authoring — usually means Step 3 was skipped. If you do not pick spine workflows, the agent has nothing to anchor on and emits 🔴 on questions it could have answered. Pick the spine; author the spine; iterate.

Where to go after Day 1​

  • Week 1: triage the Missing Knowledge inbox daily. Author the entries users actually want.
  • Week 2: pick the workflow with the most 👎 feedback in AI Reports and improve it (usually a missing Knowledge entry or a brittle Form).
  • Week 3: review your domain_global set; split anything over 700 tokens; promote anything page-scoped that turns out to be cross-cutting.
  • Month 1: re-read Authoring for the agent. You will read it differently now that you have authoring experience.