[[categories]]
name = "Getting started"
tips = [
"tix init writes a default tix.toml, a Default board under docs/boards/, and a Backlog milestone; run it once per repository.",
"Run tix with no arguments from anywhere inside the repository to open the kanban TUI; the root is found by walking up to the nearest tix.toml.",
"tix create --title 'First issue' --priority high --labels docs files an issue without leaving the shell.",
"tix new opens the same TUI as tix, but with the create-issue form already open.",
"tix status prints one count per board column plus the total, so a script can read the board without parsing a table.",
"tix list shows your issues in the board's entry column, one line each; --all lists every active issue and --columns title,status chooses and orders the columns.",
"tix render draws the current board once and exits — useful in a commit hook or a status line.",
"An issue can be referenced by number, id, filename fragment, or title fragment — tix edit 3 and tix edit retry-backoff both work.",
"tix --help lists every subcommand; tix help <topic> documents a feature in full.",
"Every write is a plain file write: issues are Markdown with YAML frontmatter, so git and your editor are the source of truth.",
]
[[categories]]
name = "TUI navigation"
tips = [
"The TUI has eleven top-level modes on one shell: F1 New Issue, F2 Triage, F3 Board, F4 Cycles, F5 Milestones, F6 Repos, F7 Stats, F8 Schedule, F10 Portfolio, F11 Library, F12 Config.",
"F9 is deliberately reserved for the planned Data page and does nothing today.",
"A mode chord switches modes only when the active mode does not bind that key itself — F2 inside a form is still 'open picker'.",
"The vertical navigation on the left is clickable; Ctrl+n cycles its display between Off, Small and Default.",
"Arrows and h/j/k/l move everywhere: j/k up and down, h/l left and right in every mode that has a horizontal axis.",
"Every browsing mode pages with PgUp/PgDn.",
"? opens the keybindings overlay, and / inside it filters the list fuzzily.",
"q or Esc quits from the board; Esc backs out of a modal without changing anything.",
"The TUI is mouse-aware: click, double-click, drag, right-click, scroll and hover all work, and keyboard operation is never sacrificed.",
"Right-clicking a card opens a context menu whose entries run exactly the action the equivalent key would.",
]
[[categories]]
name = "The board"
tips = [
"Enter opens the selected issue in the detail pane; e edits the same issue in $EDITOR.",
"n opens the new-issue form; Shift+C clones the selected issue into a new one.",
"d deletes the selected issue after a confirmation that names the file.",
"Space marks an issue for a batch; x unmarks it; Shift+B opens the batch modal.",
"> and < move the selected issue one column to the right or left.",
"c toggles a whole column collapsed, so a wide board still fits.",
"u toggles the sub-issue tree: children are drawn under their parent, offset one column.",
"a toggles archived issues on the board; they are hidden by default so a repository with thousands of them opens instantly.",
"r re-reads the repository from disk and rebuilds the board.",
"s opens the Config surface (F12); b starts a new board; m manages cycles and milestones.",
"Tab and Shift+Tab switch between the named boards in the tabs bar.",
"/ searches the live board; a bare number such as /55 jumps straight to issue 55.",
"f opens the structured filter modal; the active filter is shown in its own row while it is applied.",
"i opens every @mention pending for you, and a line above the hint bar announces the unread count.",
"v opens saved views: Enter applies one to the board, n saves the current board as a new view.",
"Shift+K and Shift+J (or Ctrl+Up/Ctrl+Down) reorder the selected card inside its column.",
"Ctrl+Up and Ctrl+Down are also bound to Shift+Up and Shift+Down, so either chord reorders.",
"A dragged card shows the column it would land in before you release the button.",
]
[[categories]]
name = "The detail pane"
tips = [
"Enter on the board opens the detail pane; q or Esc goes back.",
"v in the detail pane opens the issue in a read-only pager (mdterm, batcat, most, less, or more, whichever is installed).",
"Shift+V on the board is the same read-only viewer — plain v there is the saved-views modal.",
"c adds a comment, a appends an asset, and both are written through the same store the CLI uses.",
"n adds a typed relationship, Shift+E re-kinds or retargets it, d removes it — all by stable relationship id.",
"Shift+P sets, changes, or clears the issue's parent; an issue has at most one parent.",
"r opens the related-issues picker and o follows the selected related entry into its own pane.",
"Backspace walks back to the issue you jumped from, so following a chain of links is never a dead end.",
"The detail pane's back stack is bounded: a very long chain of links drops its oldest entry rather than growing without limit.",
"Shift+A hands the issue body to your configured agent command as a specification.",
]
[[categories]]
name = "Relationships and parents"
tips = [
"There are four typed relationship kinds — blocks, blocked_by, duplicates and related — and --type is always required.",
"Only a blocks edge guards a move: moving an issue toward done with open blockers asks first.",
"The untyped links: frontmatter key is retired; tix lint reports it as a finding rather than reading it.",
"tix chain <issue> prints the whole transitive blocks chain an issue holds up, in service order.",
"tix parent children <issue> lists direct children only, in the same order the TUI draws them.",
"Deleting a parent keeps its children: the reference survives and tix lint reports it as unresolved_parent.",
"tix link list --kind blocks shows only the blocking edges; an absent relationship id is a no-op rather than an error.",
"A relationship created in the TUI is byte-identical to one created with tix link, because both go through the same service.",
]
[[categories]]
name = "Cycles, milestones and rollover"
tips = [
"Cycles and milestones are ordinary Markdown records under docs/cycles/ and docs/milestones/ — not rows in tix.toml.",
"tix cycle create warns you when the new cycle's dates overlap an existing one.",
"The F4 Cycles mode groups cycles as current, future and archived, and shows statistics for the selected one.",
"When a cycle's end date passes, tix suggests moving the leftover issues forward; run tix rollover to apply it.",
"The rollover suggestion is a hint, not a mutation: nothing moves until you run tix rollover or accept the startup dialog.",
"The F5 Milestones mode is the Config surface pinned to milestones, so the registry and its progress live in one place.",
"Every issue can carry several cycles at once — tix list --group cycle buckets them as (multiple cycles).",
]
[[categories]]
name = "Cycle schedules"
tips = [
"A repeating cycle schedule generates ordinary cycle records on a cadence; nothing runs in the background.",
"tix cycle schedule detect is read-only: it reports what is ended or due, and decides nothing.",
"Every cycle-schedule mutation needs --confirm; omit it and the command previews instead of writing.",
"The only accepted timezone is a fixed UTC offset (UTC or ±HH:MM); a named IANA zone is refused so a schedule never follows daylight saving.",
"cron-like cadences are refused by name — a schedule declares a real interval and duration instead.",
"Closing an instance writes an immutable snapshot under docs/cycle_snapshots/ that is never recomputed, so later edits cannot rewrite the evidence.",
"A schedule id is an identity: a rename changes the label only, and a deleted id is never reused.",
"The F8 Schedule page's Cycle schedules tab drives exactly the same service as the CLI.",
]
[[categories]]
name = "Recurring issues"
tips = [
"A recurring series creates the same issue again on a rule; tix recurring detect shows what is due without creating anything.",
"tix recurring generate --yes creates the due occurrence, and is idempotent — re-running it does not duplicate the issue.",
"pause, resume and end are the three lifecycle states; end is terminal for generation.",
"skip records a date as never to be generated; defer just moves the cursor past it; ignore stops offering it.",
"Every recurring-series mutation needs --yes, so no occurrence appears without an explicit confirmation.",
"The F8 Schedule page's Series tab is the same surface as tix recurring, with the due warnings drawn on screen.",
"A series id is stable: renaming the series changes the label and nothing else.",
]
[[categories]]
name = "Triage inbox"
tips = [
"The triage inbox is opt-in: it exists because tix.toml has a [triage] section, which tix init writes.",
"tix triage list shows what is waiting, with the queue age derived from each issue's own entry stamp.",
"One decision per issue: accept, decline, duplicate, or defer — and a reason is required for decline, duplicate and defer.",
"Declining moves an issue to the canceled column; it never deletes or archives the issue.",
"tix triage batch --select 3,4,5 --decision accept previews; add --apply to write.",
"Each batch item reports its own outcome (applied, no-op, rejected, failed) and a rejection does not roll back the rest.",
"Every applied decision is exactly one History event carrying the actor, the timestamp and the reason.",
"The F2 Triage mode opens the same inbox the CLI reads, and t accepts, d declines, u duplicates and f defers.",
]
[[categories]]
name = "Projects, epics and roadmap"
tips = [
"A project is a first-class delivery container keyed by a stable id; the name is only a display label.",
"tix project create allocates the id, and every association stores that id, so renaming a project never re-keys anything.",
"An issue may belong to several projects at once, and a project's members are derived on read, never stored.",
"tix edit 3 --add-project p-7b1e04 associates; --remove-project drops one; --projects '' clears them all.",
"An epic is a cross-cutting container that may have one parent epic and many member issues.",
"Tasks are ordinary issues: a task-labelled issue that references an epic is a member like any other.",
"tix epic navigate e-7c4a91 walks an epic's parent, children, ancestors and depth.",
"An initiative is the strategic outcome a project, epic or milestone delivers; tix initiative create records it.",
"Initiatives associate a project by id, an epic by id and a milestone by name — that asymmetry is deliberate.",
"tix roadmap list --owner alice --label reliability --from 2026-01-01 filters one normalized plan shared by the CLI, the TUI and MCP.",
"The roadmap shows each source's own progress beside the health policy's risk state — a join, not a blended score.",
"A dangling project or epic reference is never dropped: the id stays on the issue and tix lint reports it.",
"The F10 Portfolio page has Projects, Epics and Roadmap tabs over the same services the CLI uses.",
"tix export --target roadmap writes the portable, versioned roadmap document.",
]
[[categories]]
name = "Health and stats"
tips = [
"Health is a state per issue with an audit trail: tix health set records the state, the actor and the rationale together.",
"tix health override layers an override over an issue's derived value and keeps the derivation visible underneath.",
"tix health rollup derives a parent's, cycle's or milestone's health from its contributors.",
"Every health figure is computed under a versioned policy, so a value always names the formula it came from.",
"tix health history prints the append-only History entries about one scope — never rewritten.",
"The F7 Stats page shows every scope's health with its contributors and its diagnostics, so a figure can be traced.",
"An empty rollup and a genuine zero are different states: 0/0 is complete, never confused with unknown.",
]
[[categories]]
name = "Saved views and filters"
tips = [
"A saved view is a named filter/sort/group/visibility plan, stored under [views.<view-id>] in tix.toml.",
"tix view create --name 'Active work' --filter 'status:todo' --sort due saves one.",
"The v-… id is the identity and the name is a label, so renaming a view breaks nothing.",
"Applying a view is read-only: it marks the active view and reports divergence — it never overwrites the live filters.",
"tix view status reports, field by field, how the live board diverged from the saved plan.",
"Scope is explicit (repository, project, user); project outranks repository, and a tie is a scope_conflict rather than an implicit pick.",
"user scope is share metadata — not an account and not a permission.",
"tix view delete --confirm removes the definition only, never an issue, comment or relationship.",
"The view query grammar is the same one the filter modal and tix search use — there is no second query language.",
]
[[categories]]
name = "Templates"
tips = [
"Templates live under [issue_templates.<id>] in tix.toml, keyed by an immutable stable id.",
"tix create --template <id> merges the template's defaults and prompts with the normal create flags before the issue is written.",
"Required prompts and missing references fail before any file is written, so a failed form never creates a partial issue.",
"Template prompts are data-only: a prompt renders a field, and no template code is ever executed.",
"tix template duplicate copies a definition to a new stable id, leaving the source untouched.",
"Unknown template metadata round-trips verbatim, so an extension a future version writes is not lost.",
"The F11 Library page lists both saved views and templates, with the selected record's detail beside it.",
]
[[categories]]
name = "Work-in-progress limits"
tips = [
"tix wip set <column> --max-items 3 --policy warn sets a per-column work-in-progress ceiling.",
"A limit's policy is either warn or block, and block refuses the move outright.",
"A limited board also counts estimates: --max-estimate with --unit turns a limit into a points budget.",
"WIP limits are enforced by every move surface — the CLI, the TUI and MCP judge a move by the same policy.",
"When a blocking limit refuses a move in the TUI it asks for a reason, and the reason is recorded.",
"tix wip show prints each limited column's usage beside its limit, and a column with no limit prints none rather than zero.",
]
[[categories]]
name = "Workflow categories"
tips = [
"Board columns map onto six global categories: backlog, unstarted, active, blocked, completed and canceled.",
"A column with no mapping resolves to the safe default, unstarted, and tix lint warns that the board has an unmapped column.",
"Declaring a category_map opts a board into the transition policy; a board without one keeps working unchanged.",
"Leaving a completed or canceled column needs an explicit reason: tix move <n> <col> --reason 'reopened'.",
"tix workflow categories prints the vocabulary, tix workflow show prints how this board resolves every column.",
"tix workflow transitions prints which moves are permitted from the current configuration.",
"canceled is terminal but not complete: a canceled issue is never counted as done anywhere.",
]
[[categories]]
name = "Batch editing"
tips = [
"tix bulk edit --select 3,4,5 --priority high previews the change; nothing is written without --apply.",
"The patch whitelist is status, priority, assignee, labels, dates, estimate, cycles and milestones — titles and bodies are deliberately excluded.",
"To empty a field, name it in --clear; a blank flag value means 'unchanged', never 'set to empty'.",
"A partial batch exits non-zero and prints one outcome per selected issue, and it does not roll back the ones that succeeded.",
"Re-running a batch is idempotent: the second run reports no-op for everything it already applied.",
"tix bulk link --select 3,4 --target 9 --type blocks links a whole selection to one issue in a single call.",
]
[[categories]]
name = "Archiving"
tips = [
"tix archive hides an issue by dot-prefixing its filename; tix restore brings it back.",
"An archived issue keeps its number — tix allocates above every issue, archived ones included, so a number is never recycled.",
"Default views never read archived files, which is what keeps a repository with thousands of archived issues cheap to open.",
"tix list --with-archived is the scope flag that loads them; tix search finds archived issues too.",
"Archiving changes nothing but the filename: number, status, created and every frontmatter field stay byte-identical.",
]
[[categories]]
name = "External sync"
tips = [
"tix export --target gitlab pushes local issues through glab; --target linear uses linear-cli.",
"tix import --target gitlab pulls open remote issues in; repeated runs are idempotent by remote id.",
"A blocking relation exports to Linear's relations add, so a blocker survives the round trip.",
"tix import --target speckit mirrors a local GitHub Spec Kit project as labelled issues and subissues.",
"Uploaded tokens are never read back: an [export] token is stripped before tix.toml is written, so keep them in environment variables.",
"tix init-agents writes the AI usage section into AGENTS.md, and detects .kittify/, openspec/ and .specify/ independently.",
]
[[categories]]
name = "MCP and agents"
tips = [
"tix mcp serves the Model Context Protocol over stdio, so an agent can drive the same store the CLI does.",
"The MCP surface has 103 tools, each one a thin adapter over the same service the CLI calls.",
"Every destructive MCP tool requires confirm: true; without it the call is refused and nothing is written.",
"MCP never prompts: a required value that is missing is a diagnostic, not a question.",
"Outside a repository tix mcp exits before reading a single protocol byte, so an agent cannot write into the wrong directory.",
"bulk_preview and triage_preview are read-only: they plan a batch and return it without writing anything.",
]
[[categories]]
name = "Configuration and storage"
tips = [
"tix.toml holds settings; boards, cycles and milestones are Markdown files under docs/, so a board can be reviewed in a merge request.",
"A relative issues_dir is resolved against the project root — the directory holding tix.toml — not the directory you ran tix from.",
"The issue layout is configurable: [layout] directory and filename take tokens such as {assignee}, {type}, {status}, {id}, {date} and {slug}.",
"tix layout show prints the resolved layout; tix layout migrate relocates existing files to match it.",
"move_on_change = true relocates an issue when a templated value such as its status changes.",
"An undeclared frontmatter key is preserved on write but tix lint warns about it — declare it once under [custom_attributes] keys = [...] to stop the warning.",
"Tag colors live in one *.md per tag under docs/tags/, and per-type accent colors go under [type_colors] in tix.toml.",
"Every keybinding can be overridden by name in tix.toml; docs/key-bindings.md has the complete table of action names.",
"The [repos] table names child repositories the F6 Repos mode can run tix inside, one level deep.",
"parent_repo (or the TIX_PARENT_REPO environment variable) is how a child session knows the way back to its parent.",
"tix clean removes the backup files tix writes before rewriting an issue; .gitignore already ignores them.",
"tix lint validates every issue's frontmatter and also lints the foreign repositories reachable from related_issues.",
"tix.toml is written atomically — a temp file, an fsync and a rename — so an interrupted write never leaves a half-file.",
"tix edit 3 --files opens the whole issue file in $EDITOR and never clobbers a change another writer made meanwhile.",
]
[[categories]]
name = "About this dialog"
tips = [
"Left and Right (or h/l, or p/n) walk through the tips; r shows another random one; Enter or Esc closes this dialog.",
"Press d here to turn these startup tips off — tix writes tips_on_startup = false into tix.toml.",
"Tips are on by default; set tips_on_startup = true in tix.toml to bring this dialog back.",
"Every tip here is read from tips.toml in the tix source repository, compiled into the binary.",
"This dialog shows a random tip each time it opens, so the same advice does not wear out.",
]