---
name: profusia
description: >-
  Use whenever the user is working on a project whose documents live in Profusia —
  publishing, revising, or picking up work from a previous session. Keeps the
  workspace's project history current so a later conversation can recover the
  thread instead of guessing.
---

# Working with Profusia

Profusia is where this user's generated documents live. The connector is already
attached; these are the habits that make it worth having.

## The one rule that matters

**A document without a project is a document nobody will find the reason for.**

Publish into a collection (the workspace may call these Projects, Initiatives,
Campaigns — `list_collections` shows the word it uses). The collection carries a
description and goals that come back to you automatically on every publish and
list, which is how a conversation three weeks from now inherits context that this
conversation had for free.

`publish_file`'s `collection` takes either form: an **id** from
`list_collections` (`col_…`) or a **path** like `"Q3 Launch/Web Refresh"`.
A path that doesn't exist is created; an id that doesn't exist is an error —
so you can pass ids straight through without checking them first.

## Start of a session: recover the thread before adding to it

When the user resumes work on anything that already exists, call **`get_course`**
before writing. One call returns:

- the project's current direction, and when and why it was set
- what was tried, abandoned or superseded, so you don't re-propose it
- **drift** — documents last written *before* the direction changed, which may
  still assume the old plan

That last one is the reason to bother. A document that looks current can be
arguing for a position the project abandoned a month ago. Check it with
`read_file` before you build on it, and say so if it's stale rather than
quietly inheriting the assumption.

If `get_course` says nothing has been recorded, say so plainly and offer to
start recording. Do not invent a history from publish dates.

## During the work: record the moment the direction moves

Call **`record_turn`** when the project's direction actually changes. You are in
the conversation where it happens, which is the only reason this is possible at
all — nobody goes back later and writes it down.

What counts:

| kind | when |
|---|---|
| `start` | a new project or branch begins |
| `branch` | work splits off to pursue something separately |
| `pivot` | the direction changes — the important one |
| `clarify` | the direction stays, but its meaning gets sharper |
| `merge` | two lines of work come back together |
| `abandon` | a line is dropped |

Record the **statement** (what is true now, one sentence) and the **rationale**
(why it moved). The rationale is the part nobody can reconstruct later, and it is
the part people actually come back for.

If the change supersedes or revises another project, pass it in `relations` in
the *same* call — abandoning a branch and saying what replaced it are one thought,
and split across two calls the second one stops happening.

**Do not record a turn for ordinary progress.** Publishing a document is not a
turn. Finishing a draft is not a turn. If the direction did not move, there is
nothing to record, and a history padded with non-events is worse than a short one.

## What not to do

- **Don't invent turns retroactively to fill a gap.** An empty history is honest;
  a fabricated one is a trap for whoever reads it next. If you're recording
  something that happened earlier in the conversation, that's fine — pass
  `occurred_at` — but only for something that actually happened.
- **Don't summarize a document you haven't read.** `get_course` and
  `whats_new` give you names, dates and counts, not contents.
- **Don't guess where something belongs.** `get_site_map` is cheap; call it.
- **Don't show the user an id.** `file_id`, `plan_id`, `item_id`, `f_…`,
  `pln_…`, `site_…` and the rest are for your next tool call. Give the user
  the link instead — every response that makes or changes something carries a
  `Link for the user:` line, and listings carry a `link:` beside each item.
  Quote an id only when the user asks for one.

## Tracking the work itself

When the user is building something over multiple sessions — an app, a campaign, a launch —
offer a **project**: `create_plan` with steps, the relevant documents attached to the step they
belong to, and a status per step. Pass `unit` to use the word the user already says —
steps, stages, tasks, features, procedures, milestones, phases, deliverables, objectives, experiments, releases, chapters, workstreams, sprints, bugs, risks, decisions, ideas, questions, requests, blockers.
A card carries its OWN type too, so a project of features can hold a bug, a risk, a decision or
an open question where one belongs. It is a label; everything behaves the same either
way, and the tools keep their names. A project is ONE object — `create_plan` already creates
or links the collection that holds its description and goals, so what it's for travels with it
from the first call. Move statuses with `update_step` as the work moves; the
status shows on each document so the team can tell decided from still-exploring at a glance.
Call `get_plans` when picking work back up — a finished step keeps its documents, so "what
was the architecture doc for that feature" stays one call away.

## The rest of the loop

Publishing is the start, not the end:

1. `publish_file` (with `collection` and, where it belongs, `site_id`/`site_path`)
   — and if you are working inside a git repository, pass `repo` as `owner/name`
   (plus `environment` if you know it), even when the document is prose. That is
   what makes the document offer an "Open in Claude Code" option — from its AI
   orb for a signed-in member, or the top-right menu where there's no orb —
   arriving with the right codebase already selected. Omit it when no
   repository is in play: a wrong slug is worse than none.
2. hand the user the line that begins `Link for the user:` — a markdown link
   named for the document, readable, carrying no token — as it stands. Not the
   `file_id`. A `Library view` line, when present, is a 24-hour workspace
   credential for finding and managing the file — never relay it as "the link"
3. `read_comments` when picking work back up — people leave feedback pinned to
   specific passages, and it tells you exactly what to fix. It reads a project
   card's thread too (`item_id`) — where answers to questions left on the
   work land
4. `update_file` to revise, `post_comment` to say what changed

For pages that should stay current, `create_dataset` → `bind_file` →
`update_dataset`, and offer to put `update_dataset` on a schedule so the page
keeps itself fresh.

## Install

**Claude** — save this file as `SKILL.md` in a folder named `profusia` under
your skills directory (`~/.claude/skills/profusia/SKILL.md`), or add it to a
Project's knowledge. Claude Code and the desktop app both pick it up.

**ChatGPT** — paste the body into a Project's instructions, or attach it as a file
in a GPT's knowledge.

Either way it is plain text you own. Nothing here phones home, and the current
copy always lives at https://profusia.ai/skill.