--- name: knowledge-setup description: Create a project wiki with a useful Home, starter pages, and a writing guide. --- # Knowledge setup Leave the person with a wiki they can read and navigate: a populated Home, useful starter pages, and a writing guide. Types and relations are optional; defining them alone is not setup. For a request limited to checking setup or adding a type or relation, do only that work. Check what exists first. Create missing pages, fill empty bodies, and add missing context or links with small edits that preserve existing prose. Never delete, rename, archive, or replace a person's content without their approval. Re-running setup must not duplicate pages, sections, or links. The base guide is `references/wiki-guide.md` next to this file. Example relations are in `../knowledge-graph/references/relations.yaml`. ## 0. Which project Setup works on a team project's pages on the Nimbalyst server. Follow the `connect` skill first: `pages_status` must report `bound`, and every call below takes the same `repo` and `project` arguments. A project created with `pages_create_project` already has its Home page. Types defined here are always the team's. ## 1. Look before adding Read only; change nothing in this step. - Read the project's README, relevant docs and the user's brief to learn its purpose, audience, and known choices. Read the existing Home, guide, and relevant overview pages using `listPages` and `readCollabDoc`. Follow the project's guide and the `knowledge-graph` skill for all page writing, marks, citations, and links. - Search with `searchPages` before deciding a page is missing; reuse equivalent pages even when their titles differ. If a listing is truncated, follow its continuation before concluding something does not exist. Keep all reads and writes in the chosen project and section. - `tracker_list_types`: the types that exist, any `extends`, and the relations (predicates) that exist. - **Content from the earlier knowledge graph:** types `entity`, `claim`, `question`, `finding`, `investigation`, `ontology-proposal`, project types that held decisions (`keystone`, `decision-exploration`), `.nimbalyst/labels.yaml`, predicates whose only `subjectKinds` is `entity`, and an `entity` titled "How we write this wiki". Report them as "earlier model, left in place". Do not edit or remove them, do not add labels or vocabulary packs, and never pass `labels` to `tracker_define_type`. Offer the move into pages as a separate job the person starts (`../knowledge-graph/references/migrating-v1.md`). ## 2. Understand what would make this wiki useful For a new wiki or a substantial setup repair, have a short discovery conversation before writing. Use what the person already said and what the project contains; ask about the remaining choices that would change the result. Do not treat a repository's contents as proof of the person's intended audience or purpose. Skip this step for a narrow type/relation change or a check-only request unless a missing answer blocks that task. Use the host's interactive question tool. Prefer one prompt with a few fields, suggested answers based on the project, and an escape hatch for the person's own answer. Pre-fill known preferences. Cover the useful gaps among: - **Purpose and audience:** who will read it, and what should it help them do? Onboard teammates, guide coding agents, preserve product intent, or compare research are different starting points. - **First useful result:** which questions should the wiki answer immediately, and which areas matter most? Let the person adjust a suggested page list instead of asking them to invent a hierarchy. - **Sources and boundaries:** which existing docs, sessions, or other material should inform it, and what should stay outside the wiki? Ask about missing or ambiguous sources, not files you can locate yourself. - **Depth and upkeep:** a concise orientation or a deeper reference; what should agents keep current as work happens? Discuss types in terms of things the person wants to browse or compare, not schema terminology. Wait for the answers before making dependent choices. Ask a follow-up only when an answer leaves a consequential ambiguity; do not turn setup into a questionnaire or repeatedly confirm settled choices. If the brief already answers these questions, proceed. If the person explicitly delegates the choices, use project-grounded defaults and state the assumptions. Use the answers to choose the pages, their depth, and any types. Reflect the intended audience and purpose in Home. A research wiki need not inherit a software project's Product/Design structure. Once the direction is clear, build the wiki; do not require a separate approval for each ordinary page creation. ## 3. Guide page - **Base version:** 5. The base text is `references/wiki-guide.md`, unchanged; its last line names the version. - **Find it.** `pages_status` returns its `guideLink` when the project has one; `listPages` gives its `uri`, which you read with `readCollabDoc`. - **Missing:** create it with `createSharedDoc` (`section`, `title: How we write this wiki`, no parent, `after` the Home page's node when there is one, `initialContent` = the base text). Read it back at the returned `uri` and confirm the text is there. - **Only the earlier guide exists** (an `entity` titled "How we write this wiki"): leave it. Offer to create the new page and carry over the team's own edits that still apply; create it only after the person approves the merged text. If the guide page exists, **never overwrite it**. Compare it with the base, ignoring whitespace: - Same text: "already present, matches base version 5". - Different text, version line 5: the team edited it. Report "already present, edited by the team". - Different text, older or missing version line: the base changed since it was installed, and the team may also have edited it. Report both. When it differs, offer a diff and a merge that keeps every team edit and proposes only the base changes that do not conflict. Write it with `applyCollabDocEdit` only after the person approves the merged text. A team that rewrote the guide on purpose may decline; that is final until they ask again. ## 4. Home and starter pages Do this as part of setup, without handing the person a second command to run. - **Home:** reuse the section's existing Home. If none exists after lookup, create a root page titled Home with `createSharedDoc`. Write a short project introduction and an annotated list of links that helps a newcomer find their way. Use the returned page `link` in content and its `uri` for body edits; never guess identifiers. A new section's Home holds starter text that Nimbalyst wrote ("This is your personal home page..." or the team Home's welcome and how-to-add-a-page lines); replace that starter text with your introduction rather than adding below it. Keep anything a person wrote. - **Titles and page fields:** every page shows its title above the body, so start each body with text, never with the title (or the project name) as a heading. Give each overview page a one-line `summary`, a `status` (`current` for what is true now, `draft` while it is thin), and an `owner` when the person told you who keeps it current, with `setPageFields`. - **Starter pages:** follow the user's requested structure; otherwise choose a small set suited to the project. For a software project, start with Product (who it serves and why), Design (principles, constraints, and key choices), and Decisions and open questions (an index linking to the pages that own them). Add Initiatives or other sections when the brief or existing material supports them. Use plain pages for these overviews; do not create a type for each section. - **Real content:** write a few useful, source-backed paragraphs on each overview. Preserve attribution and put decision marks in the page they affect; the index links to those pages or places a marks view rather than copying decisions. Link to plans and trackers instead of copying task lists. If information is missing, say specifically what is unknown; never invent a product direction, decision, owner, or status. With too little context to write even a project introduction, ask one focused question through the host's question tool. - **Placement and navigation:** create pages with `initialContent` and the appropriate `parentFolderId`; use the existing layout, or a shallow root structure for a new wiki. Add links from Home to the guide and every starter page, with a short explanation of each. Link related pages in their prose. Do not leave empty section shells or disconnected pages and call setup complete. - **Existing pages:** read before editing with `applyCollabDocEdit`. Fill empty pages and add only missing material; leave established wording and custom navigation intact. If a change would replace them, ask first. A failed or ambiguous write needs a read-back before retrying creation. ## 5. Types (when useful) Define types only when the person asks or agrees, including during discovery; do not ask again about an agreed type. If still unclear, ask what the team keeps several of and would want in a table. Suggest from what the project already discusses (module, technology, competitor, person are common); the team decides. A type for a single page is not a type. - **Reuse first.** Match on id and display name in `tracker_list_types`. If the project already has a fitting type (for example a `competitor` type), use it. - **Define** with `tracker_define_type` and `schema`. Keep it small: `title` plus two to four single-valued fields (select, string, boolean, user, date). Only single-valued fields show in a page header; multi-valued fields show only in tables. No `labels`, `kind` or qualifier fields. ```json { "type": "technology", "displayName": "Technology", "displayNamePlural": "Technologies", "icon": "memory", "color": "#7c3aed", "modes": { "inline": true, "fullDocument": true }, "idPrefix": "tech", "idFormat": "ulid", "fields": [ { "name": "title", "type": "string", "required": true }, { "name": "maturity", "type": "select", "options": [ { "value": "ga", "label": "Generally available" }, { "value": "beta", "label": "Beta" }, { "value": "deprecated", "label": "Deprecated" } ] }, { "name": "inStack", "type": "boolean" } ], "roles": { "title": "title" } } ``` - **Subtypes** set `extends: ` and declare only what they add (`{ "type": "library", "extends": "technology", "displayName": "Library", "displayNamePlural": "Libraries" }`). A subtype's pages show in its base type's table and nest inside it in the tree. - **Existing types:** never pass `overwrite` without the person's approval, and then keep every existing field and option. Never pass `confirmDestructive` on your own. - **Place each new type** where the person wants it with `moveSharedItem` (`kind: type`, `itemId` = the type id, `newParentFolderId` = the parent page, or none for the top of the section). A subtype is not placed; it shows inside its base. Write two or three sentences on an empty type page saying what belongs in it, and link it from the relevant overview. Do not create sample items just to fill its table. ## 6. Relations (when useful) Add a relation when the team links two of its types often and the link means one specific thing ("built on", "competes with"). Each one is a predicate with: - `id` (kebab-case), `label`, and `inverseLabel` (how it reads from the other page; the same as `label` when `direction: symmetric`) - `subjectKinds`: the types a link can be written on; `objectKinds`: the types it can point at. Use the project's type ids; subtypes are covered through `extends`. - `valueShape: entity` and `direction: directed` or `symmetric`. No qualifiers. Copy the shape from `../knowledge-graph/references/relations.yaml`, renamed to the project's types, and send only new ids with `tracker_define_type` (`predicates: [...]`; it merges by id and keeps the rest). Do not add generic relations ("related to", "depends on"): a plain link says that already. - An existing id with a different definition is a conflict: keep it and report it. - Adding `objectKinds` to an existing predicate narrows it and counts as destructive. Propose it to the person; only with their approval pass `confirmDestructive`. - Never send `removePredicates`. ## 7. Verify and report Read back every created or edited page and check its content, tree placement, and links against the person's intended use. Setup is complete only when Home introduces the project, links to the guide and useful starter pages, and those pages address the agreed priorities with grounded content or clearly stated gaps. Report blocked writes or missing context as incomplete; successful type creation is not a substitute. Lead the report with a link to Home and the pages created or filled. Briefly note any types or relations added, earlier-model content left in place, conflicts, and information still needed. For a check-only request, report these findings without making changes.