The model

Six nouns, and which of them owns the others.

Nothing here is a screen. It is what the screens are about, and the rest of this documentation uses these words without redefining them.

Teams

A team is the unit of ownership and the unit of vocabulary. A team owns its tickets — every ticket has exactly one — and it owns the list of statuses those tickets may be in, the labels they may carry, and the custom fields they may hold. Two teams in the same instance can disagree about all three and neither is wrong.

Teams nest: a team may have a parent, recursively, and a query for a team's work can be asked of its subtree. The sidebar draws the nesting but caps the indentation at two levels, so a four-deep nest renders levels two, three and four at the same indent.

Projects

A project groups tickets and carries a lead, a status, dates and health updates. It is the unit a roadmap and a timeline are read at, and it is where a document is attached when the document explains a body of work rather than one ticket.

A ticket's project must belong to the ticket's own team. The rule is checked identically when a ticket is created and when it is patched, and it is what keeps a project from becoming a second, competing hierarchy.

One exception, deliberate: a project that belongs to no team is transverse and belongs everywhere. That is the only shape in which a project ever holds tickets from more than one team — and the timeline's widening, where it draws in everyone else with work in a shared project, is live only for a transverse project and inert for every other.

Moving a project to another team is refused with a 409 when tickets elsewhere still point at it, rather than silently clearing their project. An archived ticket can hold the refusal open with no way to reach it from the screen; that is a known rough edge.

Tickets

The unit of work. A ticket belongs to one team, optionally to one project, and carries the fields below plus a description, an assignee and whatever custom fields its team has declared.

KAN-142: A short identifier of the team's own, allocated inside the insert transaction from a counter on the team row. It is what a ticket is called out loud, and what /t/KAN-142 resolves.
status: One of the team's own statuses — see below. Never a global list.
priority: None, low, medium, high or urgent. A closed vocabulary, the same everywhere.
start, due: Either, both or neither. One bound alone is a milestone, and the scheduler keeps it that way rather than growing the other.
estimate: Points, on a truncated Fibonacci scale — 1, 2, 3, 5, 8, 13 — and nullable. Not estimated and estimated at zero are different states, so every sum excludes the unestimated and every screen showing a sum also says how many tickets it could not speak for.

Comments with mentions, labels, favourites, and time entries all hang off a ticket. So does its activity: who changed what, when, and through which door — a change made by an agent says the name of the person whose token it used.

Statuses are a team's own words

A new team starts with six statuses, and that is the last thing Kanso decides about them. A team renames them, reorders them, adds a seventh and removes one it does not use. The list, the board, the charts and every MCP tool then say that team's words back.

Backlog, Todo, In progress, In review, Done, Canceled — the six a team starts with, and the six colours the palette ships.

Which means there is no global status to filter on across two teams that have diverged. That would make the board useless above one team, so each status also declares what it means.

The five meanings

Every status, renamed or not, belongs to one of five categories. They are fixed, they are never shown as a status, and they are what a question spanning two vocabularies is asked in: meaning:started is everything under way, in every team, whatever each one calls it.

backlog: Noted, not yet queued.
unstarted: Queued, nobody has started.
started: Under way — In progress and In review both, by default.
completed: Finished.
canceled: Dropped, and not finished.

It is also what makes a ticket survive a move. A ticket moved into a team that has never heard of its status arrives in that team's first status of the same meaning, by position — and, only when the destination cannot express that meaning at all, in its first status. It never arrives in a word nobody there can read.

Edges between tickets

blocks is directed and is the only kind the scheduler reads: one finish-to-start arrow saying the successor cannot begin before its predecessor ends. Moving a date settles the whole connected component around the change, not the direct successors alone.

A dependency that would close a cycle is refused with the path it would have closed, rather than with the words “cycle detected” — which is not something anybody can act on.

A ticket may have a parent ticket. Sub-tickets are a hierarchy for reading, not a second scheduler: nothing is rolled up automatically.

relates is symmetric and carries no order; duplicates is directed and points at the survivor. Both exist so that “this is the same as that” can be navigated instead of written in a description where nothing can follow it.

Documents

A document is a Notion page, referenced by Kanso rather than copied into it. The page that explains a decision is attached to the work it decided, so it is found from the ticket instead of from a folder in a second tool.

The reference is many-to-many on both sides: a document can be attached to several projects and several tickets, and a ticket can carry several documents. Kanso also mirrors its own document index into Notion, which is the fourth of the four databases.

Custom fields

A team declares its own fields — text, number, boolean or select — and every ticket on that team can carry a value for each. A field is defined once and valued per ticket, so the settings screen can list what exists, a rename is a rename, and a typo is a mistake rather than a new field.

They are on the wire in every ticket response, including the MCP tools', from before there was anything to put in them: a shape that gains a key later is a shape every existing integration has already pinned.

Who may do what

Three instance roles that may write — owner, admin, member — and a fourth, viewer, that reads and never writes. Owner and admin are the two that may configure the instance.

Reads are open; only writes are scoped. No GET in Kanso is scoped by team: any authenticated user can read any team's tickets, projects, timeline and roster. That is deliberate and one-directional — the cross-team timeline exists to show who else is doing what, and hiding some of “who else” removes the reason it was built. Writes are gated per team, everywhere.

Deleting is not archiving. Archived is a decision with no clock on it; deleted is a thirty-day countdown, and the two are separate tabs with separate counts in Trash.