docs: track chat channel rules and Greptile configuration (#16172)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Chat channels connect shared task workflows to several platforms.
> - Recent refactors moved platform behavior into named channel folders.
> - Authors and reviewers need a durable rule that preserves these
boundaries.
> - Review settings also need version control and an explicit source of
rules.
> - This pull request adds scoped MDC rules and a staged migration of
supported Greptile settings into Git.

## Linked Issues or Issue Description

**Issue type**

Missing documentation and versioned review configuration.

**Where is the issue?**

Root contributor instructions, chat channel architecture guidance, and
Greptile configuration for this repository.

**What's wrong?**

The channel folder boundary is established in the refactor but has no
focused rule for future changes. Greptile settings and custom context
are maintained in the dashboard.

**Suggested fix**

Keep canonical rule bodies under `rules/`. Route coding agents through
`AGENTS.md` and load matching rules through `.greptile/files.json`.
Preserve supported review settings in `.greptile/config.json` and
document the remaining dashboard controls.

Related work: #15823 and #16080. A search for related rule PRs found no
duplicate configuration change.

## What Changed

- Add `rules/chat-channel-platform-boundaries.mdc`. Its scope covers
`server/src/services/chat-channels/**` and the sibling
`chat-channels.ts` entry point.
- Define provider folder ownership, shared workflow boundaries, typed
dependencies, behavior-preserving extraction, and dispatch exceptions.
- Add rule-loading instructions to root `AGENTS.md` and
`.greptile/rules.md`.
- Add explicit, scoped context references in `.greptile/files.json`.
- Record observed review triggers, the Dependabot exclusion, Base tier,
High strictness, summary options, fix prompts, status checks, and
disabled auto-approval in `.greptile/config.json`.
- Move existing PR-description, source-file growth, and
repository-specific screenshot guidance into
`rules/pull-request-review.mdc`.
- Document supported settings, remaining dashboard controls, and the
staged cutover. The dashboard was inspected read-only; no settings or
saved rules were changed.

## Verification

- Parse both MDC headers with Ruby `YAML.safe_load`: passed.
- Parse both Greptile JSON files and verify documented field types and
observed values: passed.
- Verify all four context references resolve to repository files:
passed.
- Compare scoped MDC globs with the corresponding Greptile scope:
passed.
- Check ten positive and negative scope cases with Node
`path.matchesGlob`: passed. Includes the service entry point, nested
provider files, and unrelated runner, connection, and UI paths.
- Verify the scope covers all 101 tracked chat-channel files: passed.
- `git diff --check`: passed.
- Application typecheck, `pnpm test:run`, and build were not run
locally. This change contains only guidance and reviewer configuration,
and this worktree has no installed application dependencies. No runtime
behavior or application tests changed.
- Greptile reviewed commit `32647dfd001289a297b9d43c381371da8575df38`:
5/5, eight files reviewed, zero comments. Hosted CI is still running.

## Risks

- Instructions depend on agent and reviewer compliance; these files are
not deterministic lint rules.
- The new MDC directory is explicitly routed through `AGENTS.md` and
Greptile. Cursor does not automatically discover arbitrary `rules/`
directories.
- This preserves the observed High strictness setting, which the
dashboard says omits P2 comments. It does not change that review policy.
- Dashboard instructions and custom rules remain additive. Their copies
were not disabled during read-only inspection. The repository-specific
no-screenshot rule explicitly takes precedence over the conflicting
older organization instruction.
- Draft review, the required 5/5 status threshold, image badges, and
other controls without documented config equivalents remain in the
dashboard. See `.greptile/README.md` for the inventory and cutover
limitations.

## Model Used

OpenAI Codex based on GPT-6. The exact runtime model ID and
context-window size are not exposed in this session. Used reasoning,
repository inspection, shell validation, official documentation, and
read-only browser inspection.

## 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 (configuration parsing and
scope checks described above; application suites were not run)
- [x] I have added or updated tests where applicable (no runtime change;
checked configuration directly)
- [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
- [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 <[email protected]>

.greptile/README.md

@@ -0,0 +1,71 @@
+# Greptile configuration
+
+This directory tracks the supported review configuration for
+`paperclipai/paperclip`. It was prepared from a read-only dashboard inventory
+on 2026-10-13. No dashboard settings or custom context were changed.
+
+- `config.json` records the observed review settings supported by Greptile's
+  documented file schema.
+- `files.json` loads repository context and scopes architectural rule files.
+- `rules.md` explains how to apply the canonical Markdown rules in `rules/`.
+
+## Settings migrated to Git
+
+| Dashboard setting | Repository configuration |
+| --- | --- |
+| Automatic reviews on all events | `autoReview: ["open", "push", "rebase"]` |
+| Exclude `dependabot[bot]`; remaining reviews use Base | `excludeAuthors`, `effort: "base"` |
+| High strictness (dashboard says it does not comment on P2s) | `strictness: 3` |
+| Do not replace the PR description | `shouldUpdateDescription: false` |
+| Include PR summary, confidence score, and findings; no sequence diagram | The four section settings in `config.json` |
+| Summary is not collapsible; default-open option is off | `summarySection.collapsible` and `defaultOpen` are `false` |
+| Include a prompt to fix findings | `fixWithAI: true` |
+| Status checks and status comments enabled | `statusCheck` and `statusCommentsEnabled` are `true` |
+| Auto-approval disabled; stored risk ceiling is Low | `autoApprove.enabled: false`, `riskCeiling: "low"` |
+
+The existing PR-description and 1,000-line growth guidance is in
+`rules/pull-request-review.mdc`. That file also preserves the active,
+repository-specific rule not to request UI screenshots. This resolves the
+contradiction with the older organization instruction asking for screenshots.
+
+The active dashboard pattern `**/[Aa][Gg][Ee][Nn][Tt][Ss].md` reported two files:
+`AGENTS.md` and `docs/api/agents.md`. Both are explicit references in
+`files.json`; the latter remains API context, not contributor policy. Future
+context files need explicit manifest entries. The inactive Contribution
+guidelines context remains inactive; it is not added as a separate context
+file. Rules scoped to other repositories are not copied here.
+
+## Settings still managed in Greptile
+
+The following observed controls do not have equivalents in the published
+`.greptile/` schema used for this migration. They remain dashboard settings:
+
+- Review draft pull requests: enabled.
+- Required confidence to pass the status check: 5/5.
+- Image badges: enabled.
+- Comment header: empty.
+- Default coding-agent badges: no agents shown.
+
+Repository enablement, provider authentication, billing, integrations, and
+learned memory also remain service settings. Auto-approval risk instructions,
+if used later, are explicitly dashboard-only in Greptile's reference. Do not
+invent config keys for unsupported controls.
+
+## Cutover and maintenance
+
+Greptile reads committed configuration from the reviewed branch. No reindex is
+required. Local changes alone are not visible to the hosted reviewer.
+
+File-based review settings override dashboard defaults, but dashboard rules
+and instructions are additive. The existing dashboard copies are still active.
+This is a staged migration, not a completed dashboard cleanup. After a hosted
+review verifies the configuration, an authorized maintainer can retire duplicate
+dashboard context scoped to this repository. Do not remove shared organization
+instructions while other repositories still depend on them.
+
+Keep each policy's body in `rules/`; update the `files.json` scope together with
+the rule's MDC frontmatter. The chat-channel rule includes both the directory
+and its sibling service entry point. See `rules/README.md` for authoring steps.
+
+References: [configuration and precedence](https://www.greptile.com/docs/code-review/greptile-config),
+[supported fields and file references](https://www.greptile.com/docs/code-review/greptile-config-reference).

.greptile/config.json

@@ -0,0 +1,28 @@
+{
+  "autoReview": ["open", "push", "rebase"],
+  "excludeAuthors": ["dependabot[bot]"],
+  "effort": "base",
+  "strictness": 3,
+  "shouldUpdateDescription": false,
+  "summarySection": {
+    "included": true,
+    "collapsible": false,
+    "defaultOpen": false
+  },
+  "confidenceScoreSection": {
+    "included": true
+  },
+  "issuesTableSection": {
+    "included": true
+  },
+  "sequenceDiagramSection": {
+    "included": false
+  },
+  "fixWithAI": true,
+  "statusCheck": true,
+  "statusCommentsEnabled": true,
+  "autoApprove": {
+    "enabled": false,
+    "riskCeiling": "low"
+  }
+}

.greptile/files.json

@@ -0,0 +1,24 @@
+{
+  "files": [
+    {
+      "path": "AGENTS.md",
+      "description": "Repository contributor instructions and routing to scoped architecture rules."
+    },
+    {
+      "path": "docs/api/agents.md",
+      "description": "Agent API documentation retained from the existing Greptile agent-file context. This is API reference material, not contributor instructions."
+    },
+    {
+      "path": "rules/pull-request-review.mdc",
+      "description": "Existing Paperclip review guidance for PR descriptions, UI evidence, and growth of large source files."
+    },
+    {
+      "path": "rules/chat-channel-platform-boundaries.mdc",
+      "description": "Architecture requirements and review criteria for separating chat channel platform implementations from shared orchestration.",
+      "scope": [
+        "server/src/services/chat-channels/**",
+        "server/src/services/chat-channels.ts"
+      ]
+    }
+  ]
+}

.greptile/rules.md

@@ -0,0 +1,12 @@
+# Repository rule loading
+
+The `.mdc` files under `rules/` are repository review requirements.
+`.greptile/files.json` identifies the rule files to read for matching source
+paths. Read their full Markdown bodies and apply their review criteria and
+allowed exceptions to the affected code.
+
+Each rule's YAML frontmatter declares its scope with repository-relative
+`globs`, or `alwaysApply: true` for a repository-wide rule. Respect that scope;
+do not apply a channel rule to unrelated subsystems. Keep the policy in the
+referenced file as the source of truth rather than maintaining a separate copy
+in dashboard instructions.

AGENTS.md

@@ -26,6 +26,20 @@ authoring runbook for provider research, supported transport/auth patterns,
 credential handling, branding, implementation, testing, live proof, and PR
 submission.
 
+### Scoped repository rules
+
+Before editing or reviewing files, read the matching rules in `rules/*.mdc`.
+Each rule has Markdown content and YAML frontmatter: `globs` contains
+comma-separated, repository-relative file patterns, and `alwaysApply: true`
+means the rule applies throughout the repository. Read all rules whose scope
+matches the affected files. These rules supplement this file and any applicable
+nested `AGENTS.md` instructions.
+
+For `server/src/services/chat-channels.ts` and everything under
+`server/src/services/chat-channels/`, read
+[`rules/chat-channel-platform-boundaries.mdc`](rules/chat-channel-platform-boundaries.mdc).
+See [`rules/README.md`](rules/README.md) for rule authoring and Greptile setup.
+
 ## 3. Repo Map
 
 - `server/`: Express REST API and orchestration services

rules/README.md

@@ -0,0 +1,31 @@
+# Repository rules
+
+Keep architectural guidance in focused `.mdc` files here. Each file is Markdown
+with YAML frontmatter containing a `description` and an `alwaysApply` boolean.
+For scoped rules, set `alwaysApply: false` and provide comma-separated,
+repository-relative `globs`. For repository-wide rules, set `alwaysApply: true`
+and omit `globs`. Use `**` for all descendants of a directory. Include sibling
+entry points explicitly when needed.
+
+Root `AGENTS.md` tells coding agents to read matching rules before editing or
+reviewing code. This directory is a repository convention: Cursor does not
+automatically load it as `.cursor/rules/`, and the `.mdc` extension alone does not
+make a tool apply a rule.
+
+Greptile reads matching rule files through `.greptile/files.json` and receives
+loading instructions from `.greptile/rules.md`. The rule body remains here as
+the single source of truth. Repository configuration takes effect when the
+files are available on the reviewed branch; local files alone are not visible
+to the hosted reviewer.
+
+When adding or changing a rule:
+
+1. State the scope, required behavior, examples, exceptions, and review criteria.
+2. Add its path to `.greptile/files.json`. Copy its `globs` into that entry's
+   `scope` array, one pattern per element. For `alwaysApply: true`, omit `scope`.
+3. Keep the rule's frontmatter and the Greptile scope synchronized. Verify that
+   the scope covers representative files and excludes unrelated directories.
+4. Keep detailed policy in the rule file instead of copying it into tool settings.
+
+See the [Greptile file-reference documentation](https://www.greptile.com/docs/code-review/greptile-config-reference)
+for the manifest format.

rules/chat-channel-platform-boundaries.mdc

@@ -0,0 +1,60 @@
+---
+description: Keep chat channel platform implementations in their own folders and shared orchestration independent of platform details.
+globs: "server/src/services/chat-channels/**,server/src/services/chat-channels.ts"
+alwaysApply: false
+---
+
+# Chat channel platform boundaries
+
+## Scope and purpose
+
+This rule applies to `server/src/services/chat-channels/` and its sibling
+`server/src/services/chat-channels.ts` service entry point. Keep each platform's
+implementation cohesive while letting common workflows support different
+platforms through explicit contracts.
+
+## Required structure
+
+- Put platform-specific code in `chat-channels/<platform>/`. This includes
+  payload parsing, SDK and transport calls, protocol details, credential and
+  setup behavior, message formatting, and platform-specific workarounds.
+- Use the existing platform directories, such as `telegram/`, `slack/`,
+  `discord/`, `github/`, `microsoft-teams/`, and `imessage-photon/`. Organize files
+  within each directory by responsibility, such as `messages.ts` or `setup.ts`.
+- Keep shared product behavior in the service or cohesive workflow modules,
+  such as `inbound/`, `interactions/`, and `publications/`. Shared code owns common
+  company isolation, authorization, task lifecycle, ordering, and persistence
+  invariants. Provider details must not bypass those invariants.
+- Use explicit typed inputs, outputs, capabilities, or callbacks at the boundary.
+  Shared workflows should consume normalized values rather than interpret one
+  platform's raw payloads. Pass the dependencies a module needs instead of a
+  large mutable service context.
+- Reuse existing contracts and shared implementations when their behavior is
+  actually common. Preserve meaningful platform differences. Add a new
+  abstraction only when a concrete workflow needs it.
+- When extracting code, preserve transaction ownership, queue ordering,
+  idempotency, runtime state lifetime, and callback timing. Moving code must not
+  create duplicate state or a second owner for a side effect.
+
+## Examples and allowed exceptions
+
+- Telegram edited-message parsing belongs in `telegram/messages.ts`; a shared
+  delivery workflow can consume its normalized message or lifecycle event.
+- Shared orchestration may import platform modules and select an implementation
+  by provider name. Small registration tables and dispatch branches are valid;
+  the selected branch should delegate protocol behavior to the platform module.
+- Keep behavior used by several platforms in a shared module when its inputs and
+  semantics are independent of those platforms. Do not make one platform import
+  another platform's implementation merely to reuse a helper.
+- Existing code outside these boundaries can be migrated incrementally. Apply
+  the rule to new or materially changed behavior; an unrelated fix does not
+  require moving the whole subsystem.
+
+## Review criteria
+
+Flag new or expanded platform-specific implementation in the service entry
+point or shared workflow modules, direct dependencies between unrelated
+platform implementations, and shared contracts that expose a platform's raw
+payload or SDK types. Identify the behavior and the appropriate owning folder.
+Allow the registration and dispatch exceptions above, and do not request an
+abstract provider framework solely to remove a small dispatch branch.

rules/pull-request-review.mdc

@@ -0,0 +1,22 @@
+---
+description: Existing Paperclip pull request review requirements migrated from Greptile settings.
+alwaysApply: true
+---
+
+# Pull request review
+
+This rule applies when reviewing pull requests throughout this repository.
+
+- Follow the PR description guide in `CONTRIBUTING.md` and the sections in
+  `.github/PULL_REQUEST_TEMPLATE.md`. Request missing thinking paths and missing
+  explanations of what changed, why it matters, the benefits, verification, or
+  risks.
+- Do not request UI screenshots in PR reviews for this repository. Visual state
+  verification is described through component tests, enumeration of states in
+  the PR description, and use of existing design tokens. This repository rule
+  takes precedence over the older organization instruction to request
+  screenshots for visual changes.
+- When a PR grows a source file from fewer than 1,000 lines to more than 1,000
+  lines, require a concrete reason for keeping the implementation together.
+  Flag an unexplained crossing and suggest a cohesive extraction. This check
+  does not require unrelated cleanup of every existing large file.