## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The board UI renders agent/user-authored Markdown in task
descriptions, comments, and other work-thread surfaces
> - Those Markdown surfaces often live inside cards and containers that
constrain overflow
> - Ordered-list markers are painted outside the list content box, so
too little inline padding can clip multi-digit markers at the left edge
> - This pull request keeps the shared Markdown list gutter compact
while giving ordered lists enough marker space for two- and three-digit
counters
> - The benefit is that long numbered lists in board-facing Markdown
render correctly without widening unordered-list gutters or changing
API, data, or editor behavior
## Linked Issues or Issue Description
No public GitHub issue found.
Bug description:
- What happened: rendered Markdown ordered lists with multi-digit items
could show clipped marker digits when the list was flush against an
overflow-constrained container.
- Expected behavior: ordered-list markers such as `10.` and `100.`
should render fully in task descriptions and comments.
- Steps to reproduce: render a `.paperclip-markdown` ordered list with
at least 100 items inside a container that clips overflow and has no
extra left gutter.
- Paperclip version/commit: current `master` before this PR.
- Deployment mode: board UI, deployment-mode independent.
Related search result:
- Refs #2049 because it also touches rendered Markdown list
presentation, but it styles GFM task-list checkboxes and does not
address ordered-list marker clipping.
## What Changed
- Set the shared `.paperclip-markdown` list padding to a compact
`1.5rem` baseline for bullets and lists.
- Added an ordered-list-only `2.5rem` padding override so
outside-positioned multi-digit ordered-list markers have enough
inline-start room.
- Added a focused stylesheet regression test that verifies
unordered-list gutters stay compact while ordered lists keep the larger
marker gutter.
- Restored the exact maintainer-skill marker phrase expected by the
existing server skill utility contract test, fixing an unrelated
latest-head CI failure from current `master`.
## Verification
- `pnpm --filter @paperclipai/ui exec vitest run
src/components/MarkdownListStyles.test.ts`
- `pnpm check:token-gates`
- `pnpm --filter @paperclipai/ui build`
- `pnpm exec vitest run
server/src/__tests__/paperclip-skill-utils.test.ts`
## Risks
- Low risk: ordered lists in rendered Markdown get a larger left gutter;
unordered lists keep a smaller shared gutter.
- Low risk: the skill-doc marker change is text-only and matches the
existing server test contract.
- No database, API, migration, auth, adapter, or telemetry changes.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex, GPT-5 coding agent, tool-enabled software-engineering
session. Context window size was not exposed by the runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The board UI includes an agents sidebar so operators can see which
agents are currently active.
> - That sidebar depends on live-run polling, heartbeat events, and
cross-tab cache sharing to stay current without overloading the API.
> - The sidebar was visually churning because agents could leave the
live section immediately after a run ended, while progress events and
cross-tab broadcasts kept forcing hot query updates.
> - This pull request stabilizes live sidebar membership and makes
shared polling broadcasts monotonic/deduplicated.
> - The benefit is a calmer operator sidebar that still reflects real
live state without flashing between stale and fresh snapshots.
## Linked Issues or Issue Description
No public GitHub issue exists for this operator-facing bug.
Bug summary:
- What happened: the agents sidebar could flash or reshuffle around
active agents while live-run and heartbeat data was updating.
- Expected behavior: active and recently-active agents should remain
visually stable, and cross-tab cache sharing should not overwrite
fresher data with older snapshots.
- Reproduction context: run Paperclip with multiple tabs or rapid
live-run/progress updates and watch the agents sidebar while agents
enter/leave live execution.
- Deployment mode: local/operator board UI.
Related PR:
- Supersedes #9357, which carried the same fixes on a branch/title/body
that were not suitable for public contribution hygiene.
## What Changed
- Restored the maintainer-only warning wording in the developer skill
guide so the existing server skill-utils CI gate passes on current
master.
- Added a 120-second linger window for streamlined sidebar agent rows so
an agent does not immediately disappear from the live section as soon as
its last run ends.
- Deferred the recent-agent fallback until there are no live or
lingering agents, while keeping the live badge tied only to
actually-live runs.
- Stopped broad live-runs/heartbeats/agents-list invalidation on every
run progress event, while preserving targeted agent-detail invalidation.
- Added producer timestamps to cross-tab shared polling result messages
so older-or-equal snapshots are dropped before `setQueryData`.
- Added per-resource broadcast dedupe/rate limiting so tabs do not
rebroadcast equivalent cached data in a loop.
- Added focused coverage for sidebar linger behavior, staggered
multi-agent linger expiry, live update invalidation scope, shared
polling timestamp handling, and cross-tab broadcast dedupe.
## Verification
Run locally on the rebased PR branch:
- `pnpm --filter @paperclipai/ui exec vitest run
src/components/SidebarAgents.test.tsx
src/context/LiveUpdatesProvider.test.ts` — 44 tests passed.
- `pnpm --filter @paperclipai/ui exec vitest run
src/lib/cross-tab-poll.test.ts src/hooks/useSharedPolling.test.ts` — 10
tests passed.
- `pnpm --filter @paperclipai/ui typecheck` — exit code 0.
## Risks
- Low migration risk: the sidebar/polling changes are UI/client cache
behavior only, with no database or API contract changes.
- Sidebar visibility now intentionally lingers for 120 seconds after the
last live run; stale rows could remain briefly visible, but their live
badge is removed when they are no longer actually live.
- Cross-tab broadcasts are now more conservative; a missed publish
should be corrected by the next normal poll or accepted newer timestamp.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI GPT-5 Codex via the Paperclip Codex coding-agent runtime; exact
API model identifier and context-window size are not exposed in this
environment. The agent used terminal/tool execution for repository
inspection, focused tests, branch preparation, and PR creation.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The board UI lets operators create and edit agent adapter
configuration, including a primary model field and an adapter test
action.
> - For Cody and similar adapter forms, selecting the default model
means the model value is intentionally unset so the adapter can use its
default.
> - The adapter test path still allowed `model: undefined` to survive in
the generated adapter config, which could send an invalid test payload
instead of omitting the field.
> - This pull request normalizes create/edit adapter test config so
default-model selections omit `model` entirely.
> - The benefit is that testing an agent configured to use the adapter
default model exercises the same clean config shape that should be saved
and run.
## Linked Issues or Issue Description
No public GitHub issue was found for this local UI bug, so the problem
is described inline.
Bug description:
- What happened: using the adapter test action after choosing the
default model could include `model: undefined` in adapter config and
surface a UI/runtime error instead of testing with the adapter default.
- Expected behavior: choosing the default model should omit the `model`
field from adapter config so the adapter default is used.
- Steps to reproduce: edit a Codex/Cody-style agent with a concrete
model, switch the model selector to Default, then run the adapter Test
action.
- Paperclip version/commit: current `master` before this PR.
- Deployment mode: board UI, deployment-mode independent.
## What Changed
- Sanitized adapter test config assembly so undefined adapter config
entries are omitted before the test request is sent.
- Made create-mode current model display resilient when the model is
unset for adapter defaults.
- Added regression coverage for editing an existing agent from a
concrete model back to Default and testing it.
- Added regression coverage for create-mode testing with an
unset/default model.
- Hardened the developer skill wording used by the existing server skill
utility contract test.
## Verification
- `pnpm --filter @paperclipai/ui exec vitest run
src/components/AgentConfigForm.render.test.tsx`
- `pnpm exec vitest run
server/src/__tests__/paperclip-skill-utils.test.ts`
- GitHub PR checks on this branch are green, including Typecheck +
Release Registry, Build, General tests, e2e, verify, security scans, and
Greptile Review.
## Risks
- Low risk: this only removes undefined values from adapter test config
payloads, which aligns with the existing persisted patch behavior.
- Low risk: default-model display now treats unset create-mode model
values as an empty string.
- No database, API schema, migration, auth, or adapter runtime contract
changes.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected - check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex, GPT-5 coding agent, tool-enabled software-engineering
session. Exact context window size was not exposed by the runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Cody <cody@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip agents can load repository and catalog skills, and Codex
renders skill names and frontmatter descriptions into startup context.
> - Long descriptions consume the fixed skill metadata budget before
Codex can use the progressively disclosed skill bodies.
> - The repo `.agents/skills` descriptions and a few shipped catalog
descriptions had grown into operational documentation instead of short
trigger metadata.
> - This pull request keeps the strongest trigger language in
frontmatter while leaving detailed procedures in each skill body.
> - The benefit is lower prompt overhead, more reliable skill
triggering, and a regression guard that prevents description drift from
returning.
## Linked Issues or Issue Description
No public GitHub issue found for this maintenance item.
### Pre-submission checklist
- [x] I have searched existing open and closed issues and this is not a
duplicate.
- [x] I am working against `master`.
- [x] I have confirmed the issue originates in Paperclip's shipped skill
metadata, not in a local agent adapter or provider.
### What happened?
Codex startup renders discovered skill names and frontmatter
descriptions into a fixed skill metadata budget. Several repository
skill descriptions and one shipped catalog description had grown into
long-form operational guidance, which can force Codex to truncate
descriptions before the model has enough trigger signal to select the
right skill.
### Expected behavior
Skill frontmatter descriptions should stay short trigger summaries: one
capability sentence plus a “use when” clause. Detailed procedures should
stay in the skill body and load only after the skill triggers.
### Steps to reproduce
1. Inspect `.agents/skills/*/SKILL.md` and
`packages/skills-catalog/catalog/**/SKILL.md` frontmatter descriptions.
2. Measure folded YAML `description` values.
3. Observe descriptions above the intended short-trigger range,
including descriptions above 300 characters.
4. Run the new shipped catalog test to verify future descriptions stay
capped.
### Paperclip version or commit
Reproduced on `master` at `cc81eefb6047d8eaf57faf785f421c03dc97073c`.
### Deployment mode
Local dev / source checkout metadata inspection. This is not
database-related.
### Installation method
Built from source.
### Agent adapter(s) involved
Codex, because Codex startup uses the skill metadata prompt budget. The
metadata source itself is core repository/catalog content.
### Database mode
Not database-related.
### Access context
Not applicable; this is static repository metadata.
### Node.js version
`v22.22.2` in the verification environment.
### Operating system
Linux container environment.
### Relevant logs or output
Final measurement after this PR: 29 source `SKILL.md` files, max
description length 215 chars, 5,449 total description chars, estimated
1,363 description tokens at 4 chars/token.
### Relevant config
None.
### Additional context
The shipped catalog manifest was regenerated so the generated package
metadata matches the edited catalog `SKILL.md` sources.
### Privacy checklist
- [x] I have reviewed all pasted output for PII and redacted where
necessary.
## What Changed
- Shortened long `.agents/skills/*/SKILL.md` frontmatter descriptions to
concise capability plus use-when trigger clauses.
- Shortened the over-budget shipped skills catalog descriptions for
wireframe, Paperclip capsules, and reflection coach.
- Regenerated `packages/skills-catalog/generated/catalog.json` so
shipped metadata matches source skill frontmatter.
- Added a Vitest regression guard that caps repo skill source
descriptions and generated catalog descriptions at 300 characters.
## Verification
- `pnpm --filter @paperclipai/skills-catalog build:manifest`
- `pnpm --filter @paperclipai/skills-catalog test` — 5 files passed, 19
tests passed
- `pnpm --filter @paperclipai/skills-catalog typecheck`
- Final measurement: 29 source `SKILL.md` files, max description length
215 chars, 5,449 total description chars, estimated 1,363 description
tokens at 4 chars/token.
Note: the clean PR worktree was created from `origin/master` and
contains only this commit, but it does not have `node_modules`; running
`pnpm --filter @paperclipai/skills-catalog test` there failed at
tool/package resolution (`vitest`, `tsc`, `@paperclipai/shared`). The
dependency-equipped workspace passed the commands above before the
commit was cherry-picked onto the clean branch.
## Risks
Low risk. This changes skill metadata and tests only. The main risk is
over-trimming a useful trigger phrase, mitigated by keeping explicit
“use when” clauses and leaving detailed guidance in the skill bodies.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI GPT-5 Codex coding agent via Paperclip/Codex, with shell and
file-edit tool use. Exact API model ID and context window were not
exposed in the runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Issue-thread interactions are one of the core ways agents pause for
structured board or user decisions.
> - Adding a new interaction kind currently requires coordinated changes
across shared contracts, server behavior, UI cards, fixtures,
CLI/MCP/plugin SDK helpers, and agent guidance.
> - The checkbox-confirmation rollout established a good end-to-end
pattern, but contributors needed a durable maintainer checklist for
repeating that work.
> - This pull request adds a developer/maintainer skill that captures
that workflow inside the repo under `.agents/skills`.
> - The benefit is a reusable implementation guide for future
interaction-card work without installing that guidance on runtime
Paperclip agents.
## Linked Issues or Issue Description
Paperclip issue: [PAP-10457](/PAP/issues/PAP-10457)
This PR documents the process for adding a new issue-thread interaction
family end-to-end. There is no GitHub issue for this Paperclip-internal
skill addition.
## What Changed
- Added `.agents/skills/create-issue-interaction-ui/SKILL.md` as a
developer/maintainer skill.
- Covered shared contract, server route/service behavior, UI card
wiring, fixtures/Storybook, CLI/MCP/plugin SDK helpers, agent guidance,
invariants, and focused verification.
- Referenced the checkbox-confirmation rollout (`4d5322c82`, PR `#7649`)
as the canonical worked example.
## Verification
- `git diff --check origin/master..HEAD`
- `NODE_ENV=test pnpm exec vitest run
server/src/__tests__/paperclip-skill-utils.test.ts`
- Reviewed the added skill markdown for scope, location, and workflow
completeness.
## Risks
Low risk. This is a documentation/skill-only change under
`.agents/skills`; it does not change runtime code, database schema, API
behavior, or installed production-agent guidance.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex coding agent based on GPT-5, with shell and GitHub CLI tool
access. Exact hosted model variant and context-window size were not
exposed by the runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
Dotta
Devin Foley