--- name: istari-docs description: > Fetch and answer from Istari Digital documentation — how the platform works, web-app steps, terminology. Use for docs Q&A and docs.istaridigital.com URLs when the person is not asking you to call the live API. Do not use for uploading files, creating Systems, or writing Python against the client; those use Python Client 201 and the istari-connect / istari-models / istari-systems skills. --- # Istari Digital docs Follow this skill before answering questions about Istari Digital. ## Pick a path | The person wants | You do | | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A **first model on a live instance** (credentials in `istari.env`, or they asked you to put a CAD file on the platform) | Follow [Python Client 201 — Your first System](/markdown-source/current/tutorials/python-client/201-first-system.md): install the client, download `/quickstart/istari_quickstart.py`, run it. Do not explore the SDK or docs first. Report `system_id` and `ui_link`. | | **How the platform works** (Systems, Resources, web-app steps) | This skill + `/llms.txt`. Markdown-source, not HTML. | | **More Python after the first System** (folders, branches, change requests, links) | Install [Advanced agentic use](/markdown-source/current/icbs-build-ai/agentic-advanced.md) skills, **new session**, then read the matching `istari-*` skill. | | **Conversational API after files exist** | Istari Digital MCP with **OIDC** — [MCP Quickstart](/markdown-source/current/developers/MCP%20Service/01-quickstart.md). MCP cannot upload from disk. | ## First actions (docs Q&A) 1. Fetch `/llms.txt` on this docs site (page index). 2. Prefer **Markdown** over HTML. `/llms.txt` already lists markdown-source URLs (and keeps numbered prefixes such as `01-`, `301-`). - Latest docs: `/markdown-source/current/` - Published 2026.08: `/markdown-source/version-2026.08/` - HTML routes drop those prefixes; do not reuse an HTML path as a markdown-source path. - **Percent-encode spaces.** Directories such as `developers/MCP Service/` contain a literal space. `.../developers/MCP%20Service/01-quickstart.md` resolves; the same path with a raw space does not. 3. Read [Terminology](/markdown-source/current/intro/terminology.md) before inventing names. 4. Reading three or more pages from one section? Fetch that section's bundle instead (`/markdown-source/
-bundle.md`) — one round trip, listed at the end of `/llms.txt`. `/llms.txt` lists the Introduction, Tutorials, Web app Guide, and Developer pages one by one. Integration product pages and the deeper admin pages are covered by directory pointers instead — browse `/markdown-source/current/integrations/` or `/markdown-source/current/itAdmins/` before concluding the docs are silent on those topics. On-prem or local preview: use the same paths on whatever origin you were given. ## Fetching accurately Many agent fetch tools pipe a page through a smaller summarizing model before you see it, paraphrasing UI labels on the way. That silently breaks the "do not invent labels" rule below — the label you report was never on the page. - Ask for **verbatim** reproduction, and treat only strings you received inside quotation marks as real labels. Everything else is paraphrase. - A missing label usually means the summarizer dropped it, not that the docs omit it. Re-fetch with a narrower prompt naming the one procedure you need before reporting a gap. - If a label still does not survive intact, say which labels you are confident in and which you are not. Never reconstruct a plausible-sounding button name. - If your tooling can retrieve raw bytes (a plain HTTP GET rather than a summarizing fetch tool), prefer that for any answer that quotes UI labels, API methods, or CLI flags. ## Names - Company: **Istari Digital** (never "Istari" alone) - Product: **Istari Digital Platform** (UI + APIs + agents + SDK) - Browser UI only: **Istari Digital web app** - Registered items: **Resource** (use **file** only for on-disk bytes or a UI label that says "files") Source pages are not fully consistent — Terminology says a Job runs "on a model," the Jobs guide says "on a file." Both mean a Resource. Normalize to **Resource** in your answer, and quote a page's own wording only when quoting it directly. ## Where answers live `/llms.txt` names every page and is the index to use. Two routes it cannot express: - **Concept page vs. procedure page.** Most topics have both — `intro/key-concepts/.md` explains the model, `users/user-guide/.md` gives the web app steps. A how-to answer usually needs both, and the prerequisite is more often on the concept page. - **"My System did not pick up a new Resource version."** That is tracked vs pinned membership, in `intro/key-concepts/version-control.md` — not something the page titles suggest. Python / API: - Install and Keys vs PAT: `developers/SDK/01-setup.md` - First System from a script: `tutorials/python-client/201-first-system.md` and `/quickstart/istari_quickstart.py` - Folder encoding (API): `intro/key-concepts/systems.md` (section **Folders in the Python client**) - Web-app URLs: `developers/linking-to-the-web-app.md` - 13.x agent recipes: `/skills/istari/index.json` ## How to answer Write for a person using the platform, not for another agent. Match depth to the question: a "what is / how does X relate to Y" question gets a few sentences, not a dump of every related page. - Lead with what the platform **does**. - Do not invent UI labels, API methods, or CLI flags. If the docs do not say it, say so and point at the closest page. - Do not narrate how you found the answer (pages read, skills used, "Resources cited"). - Do not mix SDK internals (Configuration, Snapshot, Tag, TrackedFiles) or renamed-legacy terms (configurations → branches) into a conceptual answer unless the user asked for API or history. - One link at the end is enough if they might want more. Offer a follow-up ("Want the web-app steps?" / "Want how tracked vs pinned membership works?") instead of answering those unasked. For a how-to, state in this order: **required role** · **prerequisites** · **steps with exact labels** · **how to verify it worked** · **anything the docs do not cover**. Prerequisites are often on a different page than the procedure — an extraction needs a Module installed on an Agent (Terminology), which the Jobs guide does not repeat. If the answer could differ between releases, ask which version the user is on before answering, or state which tree you read (`current` vs `version-2026.08`). **Example — "Explain how a System relates to Resources and Branches"** A System groups related Resources so a team can share and version them together. Work on that grouping happens on a **branch** (every System has a permanent **baseline** branch). Adding or removing Resources, folders, or Subsystems on a branch is recorded as a **commit**. Nested Systems show up as Subsystems. Say if you want the web-app steps or how a System picks up a new Resource revision. ## Live platform **Python client (uploads, folders, first System).** Credentials live in `istari.env` or the environment — Keys first (`ISTARI_DIGITAL_API_URL` + `IDENTITY_SERVICE_SECRET_FILE`), PAT only if the instance still issues one. Never ask the user to paste a token, and never write one into a config file, a chat log, or a commit. If `istari.env` is missing, stop and send them to Developer Settings. Run `/quickstart/istari_quickstart.py` for the first System. That script already encodes folder paths and web-app links. After it prints JSON, report `system_id` and `ui_link` and stop — do not re-verify, poll Jobs, or hunt for a function that completes unless they asked. Upload Resources people should open from the tree as **models**, not `file`. New versions of the same part are **revisions**, not a second `create`. On `istari-digital-client` 13.x, `branch.commit()` on the `Istari` facade does not set folders. Use the `Client` recipe in `istari-folders` (or the quickstart) whenever the tree has folders. The facade is beta; the documented stable APIs remain `Client` / `V3Client` (`developers/SDK/`). **MCP (OIDC).** Acting through MCP needs the Istari Digital MCP service, authenticated with OIDC — an interactive browser sign-in, not a token you paste. Personal Access Tokens are not accepted by the MCP service. Follow [MCP Quickstart](/markdown-source/current/developers/MCP%20Service/01-quickstart.md). The shape of the flow is the same in every client: register the endpoint, trigger sign-in, approve in the browser. The client stores the credential itself. If you find an existing setup carrying an `Authorization: Bearer` header, that setup is stale — point the user at the quickstart instead of trying to repair the header. You cannot complete authentication on the user's behalf. The browser step is theirs. Set the server up, then tell them the one command or click that starts sign-in and wait — do not loop, retry, or attempt to fetch the endpoint directly to "check" it. Expect re-authentication. Sessions lapse. A connector that worked earlier can report that it needs authentication again; the fix is re-running sign-in, not re-adding the server. A server can be reachable and still unauthorized. Trust the client's authentication status, not connectivity. If the user is on a client whose setup the quickstart does not cover, say so and point at the quickstart's generic OIDC steps rather than guessing at that client's config format. ## If this repo is the working directory Skip this section unless the working tree contains both `docs/` and `docusaurus.config.js` — that is this documentation site, not a customer's project. Edit `docs/` (current version), not `versioned_docs/` unless asked to patch a published release. Internal links: relative paths with `.md` / `.mdx`. No UI screenshots. Prefer reading files from disk over fetching the site — no summarizing layer, and you get pages `/llms.txt` does not list. `/llms.txt` itself is generated from a hardcoded template in `src/plugins/markdown-source-plugin.js`; edit it there, not in `build/`.