Knowledge Setup

---
name: knowledge-setup
description: Set up or check a project's knowledge pages in Nimbalyst Pages -- install the editable "How we write this wiki" guide page, define the team's own page types (and subtypes) and the named relations between them, and report content from the earlier knowledge graph without changing it. Safe to re-run; it never overwrites or deletes. Use when the user wants to start a team wiki or knowledge base, add a type or a relation, or check that an existing setup is complete. To write pages, use the knowledge-graph skill.
---

# Knowledge setup

Sets up what the `knowledge-graph` skill writes into. Every step checks what exists first, adds only what is missing, and reports **created**, **already present**, **conflict**, or **needs the person**. Never delete, rename, archive or overwrite anything; stop and ask when a step would.

The base guide is `references/wiki-guide.md` next to this file. Example relations are in `../knowledge-graph/references/relations.yaml`.

<!-- desktop-only -->
## 0. Which section

If the workspace is shared with a team, set up the Team section of Pages and define types with `sharing: team` so teammates see them. Otherwise use the Personal section and `sharing: personal`. Every Pages tool takes the matching `section` (`team` or `personal`).
<!-- /desktop-only -->
<!-- remote-only -->
## 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.
<!-- /remote-only -->

## 1. Look before adding

Read only; change nothing in this step.

<!-- desktop-only -->
- `tracker_list_types`: the types that exist, their sharing, and any `extends`.
- `.nimbalyst/predicates.yaml`: the relations that exist (a missing file means none).
<!-- /desktop-only -->
<!-- remote-only -->
- `tracker_list_types`: the types that exist, any `extends`, and the relations (predicates) that exist.
<!-- /remote-only -->
- **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. Guide page

- **Base version:** 5. The base text is `references/wiki-guide.md`, unchanged; its last line names the version.
<!-- desktop-only -->
- **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`.
<!-- /desktop-only -->
<!-- remote-only -->
- **Find it.** `pages_status` returns its `guideLink` when the project has one; `listPages` gives its `uri`, which you read with `readCollabDoc`.
<!-- /remote-only -->
- **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.

## 3. Types

Define types only when the person asks or agrees. 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",
<!-- desktop-only -->
    "sharing": "team",
<!-- /desktop-only -->
    "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. Offer two or three sentences for the type's page saying what belongs in it.

## 4. Relations

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`.

## Report

End with one line per step: section, earlier-model content found (types, labels file, guide entity), guide page (link and status), types (each: created, already present, conflict, or needs placing), relations (added, already present, conflicts), and what the person still has to do in Pages.