Setup

Wiki 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 ../update/references/relations.yaml.

0. Which section

If the workspace is shared with a team, set up the Team section of the Wiki and define types with sharing: team so teammates see them. Otherwise use the Personal section and sharing: personal. Every wiki tool takes the matching section (team or personal).

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 update skill (/wiki:update) 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, their sharing, and any extends.
• .nimbalyst/predicates.yaml: the relations that exist (a missing file means none).
• 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 (../update/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. listPages for the section, then look for a page titled "How we write this wiki" and read it with readCollabDoc at its uri.
• 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.

  jsonCopy code
  {
    "type": "technology",
    "displayName": "Technology",
    "displayNamePlural": "Technologies",
    "icon": "memory",
    "color": "#7c3aed",
    "modes": { "inline": true, "fullDocument": true },
    "idPrefix": "tech",
    "idFormat": "ulid",
    "sharing": "team",
    "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: <base type> 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 ../update/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.