# Plans, goals, documentation spaces and wiki

Source: https://iskue.com/docs/plans-goals-docs/

> Cross-project plans with what-if scenarios, organisation goals with theme alignment, global documentation spaces with revisions and comments, and the per-project wiki — and which edition each needs.

Four related features sit above individual projects. **Plans** draw a cross-project timeline with dependencies, rolled-up epics and team capacity, and let you stage date changes in a **scenario** before committing them. **Goals** are organisation-level outcomes with linked tickets and a computed progress, aligned to strategic themes. **Documentation spaces** are organisation-wide page trees with revisions, comments, restriction and search. The **project wiki** is the same page engine scoped to one project.

> **Note:** **Edition:** plans (`/api/v1/plans`), goals (`/api/v1/goals`) and documentation spaces (`/api/v1/docs/spaces`, `/api/v1/docs/search`, `/api/v1/admin/docs`) require the **Professional** edition — lower editions get `403 This feature requires the PROFESSIONAL edition` and the navigation entries are hidden. The per-project **wiki** and the service-desk **knowledge base** are Standard features and are never gated. With no licence installed nothing is gated.

## Plans

A plan (`/plans`) is a named selection of **projects**, optionally narrowed by a **TQL scope** (`tqlScope`, applied on top of the projects), with a sharing scope of `PRIVATE` or `ALL_USERS`. Only the owner can edit it; others with access see it read-only (`canEdit` in the DTO).

*Create a plan and read its timeline*

```bash
curl -s -X POST $ISKUE_URL/api/v1/plans -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"Q4 delivery","shared":"ALL_USERS","tqlScope":"type IN (Epic, Story)","projectIds":["<uuid>","<uuid>"]}'

curl -s "$ISKUE_URL/api/v1/plans/<plan-uuid>/timeline" -H "Authorization: Bearer $TOKEN"
```

| Endpoint | Purpose |
| --- | --- |
| `GET /api/v1/plans`, `GET /{id}` | List plans (without projects) / one plan with its projects |
| `POST /api/v1/plans` | Create: `name`, `shared`, `tqlScope`, `projectIds` (201) |
| `PATCH /{id}`, `PUT /{id}/projects`, `DELETE /{id}` | Rename or re-scope; replace the project set; delete |
| `GET /{id}/timeline?scenario=<uuid>` | The timeline, optionally drawn with a scenario's staged dates |

### The timeline

`GET …/timeline` returns `rangeStart`/`rangeEnd` and four collections. **Items** are tickets with a bar (`start`, `end`, `scheduled`), their hierarchy (`level`, `parentTicketId`), progress (`estimate`, `totalPoints`, `donePoints`, `unassigned`) and grouping fields (`statusCategory`, `priority`, `assigneeName`, `teamName`); epics and other parents get **rolled-up** dates from their children, and items on the longest dependency chain are flagged `critical`. **Edges** are `BLOCKS` links between items, with `conflict` set when a blocker ends after the item it blocks. **Markers** are version release dates from the plan's projects. **Capacity bands** show, per team and sprint, the configured capacity against the points scheduled into it (see the sprint capacity endpoint on the scaled-agile page).

### Scenarios: what-if before commit

A **scenario** stages date changes without touching live tickets. Create one under a plan, set a `startDate` and/or `dueDate` per ticket (a null side keeps the live value), view the timeline with `?scenario=` to compare, and **commit** when the plan is agreed: each staged change is applied through the normal ticket update — screen rules, permissions and changelog included — one ticket at a time, failures are collected rather than aborting the run, and if every change applied the scenario is deleted. Only the plan's owner can commit, and every commit is written to the configuration audit log (`scenario X committed (N applied)`).

*Scenario endpoints: GET/POST …/scenarios, DELETE …/scenarios/{id}, GET …/changes, PUT/DELETE …/changes/{ticketId}, POST …/commit*

```bash
P=$ISKUE_URL/api/v1/plans/<plan-uuid>
curl -s -X POST $P/scenarios -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"name":"Slip payments by two weeks"}'
curl -s -X PUT  $P/scenarios/<scenario-uuid>/changes/<ticket-uuid> -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"startDate":"2026-11-02","dueDate":"2026-11-20"}'
curl -s "$P/timeline?scenario=<scenario-uuid>" -H "Authorization: Bearer $TOKEN"      # preview
curl -s -X POST $P/scenarios/<scenario-uuid>/commit -H "Authorization: Bearer $TOKEN"
# → {"applied":7,"failed":[{"ticketKey":"CORE-12","error":"Field 'Due date' is read-only on this screen"}]}
```

## Goals

Goals (`/goals`) are organisation-wide outcomes: a `name` (≤ 200), `description` (≤ 2 000), optional `targetDate`, a `state` of `ON_TRACK` (default), `AT_RISK` or `DONE`, and an optional strategic **theme**. Progress is never typed in — it is computed from the **linked tickets**: a ticket counts as done when its status category is DONE, and the DTO returns `totalTickets`/`doneTickets` and `totalPoints`/`donePoints` plus the linked keys. Reads need only a login; creating, editing, deleting and linking are **admin** operations. There are no goal owners, periods or parent goals, and only tickets (not projects) can be linked.

| Endpoint | Purpose |
| --- | --- |
| `GET /api/v1/goals` | All goals with computed progress |
| `POST /api/v1/goals`, `PATCH /{id}`, `DELETE /{id}` | Admin: create; update name/description/targetDate/state/`themeId` (`clearTheme`); delete |
| `POST /{id}/tickets` `{"ticketKey"}`, `DELETE /{id}/tickets/{ticketKey}` | Admin: link / unlink a ticket |
| `GET /api/v1/goals/alignment` | Goals grouped by strategic theme, plus `orphanGoals` (no theme) and `uncoveredThemes` (themes with no goal) — the **Theme alignment** panel on the goals page and in the Portfolio room |

## Documentation spaces

Documentation spaces (`/docs`, `/docs/:spaceKey`) are organisation-wide page trees, independent of any project. Administrators create a space with a `key` (≤ 20), `name` (≤ 120) and description; an **open** space can be read and edited by any signed-in user, while a **restricted** space is visible only to its members — `READER` or `EDITOR` — and to admins. Pages hold Markdown (`body` ≤ 200 000 characters, `title` ≤ 200) and nest through `parentId` (re-parent with `parentId` / `clearParent` on save).

| Endpoint | Access | Purpose |
| --- | --- | --- |
| `GET /api/v1/docs/spaces` | Any user | Spaces you may read |
| `POST /api/v1/admin/docs/spaces`, `DELETE …/{id}` | Admin | Create / delete a space (no rename endpoint yet) |
| `PUT /api/v1/admin/docs/spaces/{id}/restricted` `{"restricted":true}` | Admin | Toggle restriction |
| `GET/POST /api/v1/admin/docs/spaces/{id}/members`, `DELETE …/members/{userId}` | Admin | Members with `role` `READER` or `EDITOR` |
| `GET /api/v1/docs/spaces/{key}/pages`, `GET …/pages/{id}` | Reader | Page summaries (id, parentId, title, updatedAt) for the tree / one page with body |
| `POST …/pages`, `PUT …/pages/{id}`, `DELETE …/pages/{id}` | Editor | Create, save, delete |
| `GET …/pages/{id}/revisions`, `GET …/revisions/{rev}`, `POST …/revisions/{rev}/restore` | Reader / editor | Every save keeps a revision (rev, title, who, when); restore makes an older one current |
| `GET/POST …/pages/{id}/comments`, `DELETE …/comments/{commentId}` | Reader / editor | Page comments (≤ 10 000 characters) |
| `GET /api/v1/docs/search?q=…` | Any user | Full search across global space pages, project wiki pages and knowledge-base articles of the projects you can see |

## Project wiki

Every project has a wiki at `/projects/:key/wiki` on the same page engine — tree of Markdown pages, revisions with restore, comments — under `/api/v1/projects/{projectKey}/wiki` with the same page, revision and comment paths as above. Access follows project membership: members read, write members author, project admins delete. The wiki has no search endpoint of its own; its pages are found through `/api/v1/docs/search` (which needs the Professional edition) or by browsing.

*Revision history and restore — identical under /api/v1/docs/spaces/{key}/pages*

```bash
W=$ISKUE_URL/api/v1/projects/CORE/wiki
curl -s $W/<page-uuid>/revisions -H "Authorization: Bearer $TOKEN"
# → [{"rev":3,"title":"Release checklist","updatedBy":"Alice","createdAt":"…"}, {"rev":2,…}, {"rev":1,…}]
curl -s -X POST $W/<page-uuid>/revisions/2/restore -H "Authorization: Bearer $TOKEN"   # rev 2 becomes the current text (as a new revision)
```

> **Note:** Do not confuse the three page stores: **documentation spaces** are global and Professional; the **project wiki** is per project and Standard; the service-desk **knowledge base** (`/api/v1/projects/{key}/kb`) is per project, has a draft/published flag and is what the customer portal can surface. Docs search spans all three.