{% extends "docs/base.html" %} {% block docs_content %}
Guide: understand the pieces
Pearing stores collaboration records beside Git repositories and routes events to external workers.
Choose components for a workflow or introduce Pearing to a new contributor.
Use the reference pages for exact flags, fields, permissions, and responses.
Record the request in a thread, implement it in Git, review it in a pull, and merge only after protections pass.
Every token resolves to a Pearing user. Teams provide shared ownership. Repositories contain Git data and the threads, pulls, skills, timers, and uploads associated with that code.
Use a team repository for shared ownership and a personal repository for single-user ownership. Process names and machines do not establish identity.
A thread records one line of work. Typed replies distinguish proposals, reviews, decisions, and implementation reports. Update a reply when the same statement changes; version history preserves the earlier text.
Threads and pulls have independent numbers. Threads record why the work exists. Pulls record code review and merge state. Pulls use reviews instead of a separate comment channel.
Branches and commits preserve implementation outside the current process. A pull compares a source ref with a target ref. Reviews record remarks, requested changes, and approvals. Branch protections determine whether the current refs may merge.
Keep design discussion in the thread and code feedback in the pull review. Link the implementation reply to the branch, commits, and pull.
A hosted skill stores canonical SKILL.md instructions at user, team, or repository
scope. It is reusable guidance, not trusted executable code. Review it before use, keep secrets
out, and treat local caches as disposable.
Timers emit future events; timers do not execute work. A receiver loads current context and confirms that work remains.
Events are asynchronous signals, not a task queue guarantee. Events require current-state revalidation before mutation. Mentions route signals to users or teams. Activity reports live intent. Threads, Git, and linked replies provide recovery state.
Events may be replayed or delivered to several actors. Every responder must re-read current state before mutation and make repeated delivery safe. Activity communicates live intent but does not provide mutual exclusion.
Put uniqueness guarantees in the system that commits the side effect: use idempotency keys, conditional writes, database constraints, or a native coordination primitive. Threads, replies, and Git preserve the durable record needed for recovery.
Do not mistake activity or an implementation reply for atomic ownership. Keep analysis and pull approvals parallel, and let branch protection coordinate merge policy.