CodeRuleSet keeps the complete rulebook while loading relevant rules into the agent's context in manageable packets. Small P2 clean-code rules remain part of writing and reviewing code. Rules can belong to several subjects, such as functions, types, components, styles, accessibility, APIs and tests.

Install for Codex

Supported setup: macOS or Linux, Python 3.9+, Node.js 20.9+, Git, curl, pnpm 9 and Codex. GitHub access to the private FrankoSolomun/pro-code repository is required to clone the tooling. The public rule-reading API does not need a database password or API key.

Give Codex this URL and ask it to install the Codex workflow: https://coderuleset.com/api/setup. The agent should inspect the guide and installer, preserve your existing personal configuration, then run:

mkdir -p ~/Code
cd ~/Code
git clone https://github.com/FrankoSolomun/pro-code.git
cd pro-code
pnpm install --frozen-lockfile
python3 scripts/setup-codex.py

If the repository already exists, use that checkout and update it without discarding local changes. Do not clone over it. The installer also supports another clone location and remembers its path for the runtime.

The installer copies nine skills into your Codex configuration: rulebook-loader, rulebook-refresh, pre-pr-review, pr-check, pr-description, rulebook-author, mine-pr-rules, project-overview and review-learning. It adds or updates one marked CodeRuleSet block in AGENTS.md, preserves other content and backs up overwritten files under state/coderuleset-install-backups. It preserves unrelated skills and caches. It does not copy credentials, fetch rules, write to the database or modify company repositories.

Use --skip-agents if your existing global AGENTS.md already maintains these preferences. Use --codex-dir /absolute/config-directory for a custom Codex configuration directory; the runtime follows that directory when Codex supplies CODEX_HOME. Private language, Jira and company policies remain yours to maintain. Start a new Codex chat after installation or an update.

Everyday coding

Ask for the actual implementation in your usual language. The installed workflow loads $rulebook-loader before coding, refactoring, debugging, implementation planning or review. In a new chat it fetches one complete snapshot with full examples, stack metadata and exceptions. Searches and classification then run locally; source code and diffs are not uploaded by this retrieval workflow.

The agent reads the relevant subjects before editing, verifies applicability in the surrounding code, looks for existing helpers and keeps small clean-code improvements. A normal implementation uses focused checks, without automatically starting a full pre-PR review.

A chat reuses its own snapshot across turns. A newly saved rule is picked up by new chats. In the current chat, ask $rulebook-refresh only when you actually want to replace the snapshot. Installation and rule authoring never refresh it silently. No cache is borrowed from another chat.

Request a pre-PR review

Use $pre-pr-review or the $pr-check alias. You can name a repository and base branch, for example:

$pre-pr-review Review the whole branch against origin/main, including local changes.

The review covers the effective change from the merge base to the working tree, including inherited branch commits, staged and unstaged changes, deleted files and non-ignored new files. The agent verifies the actual base and inspects enclosing code, callers and configuration.

It reviews selected rule packets in correctness, clean-code and integration passes, audits exclusions, and records per-rule evidence against all assigned files. A separate integration audit compares old and new behavior, actual producers/consumers, null and empty states, numeric conversions, cancellation, cache policy and deployment/configuration contracts. Every changed file needs evidence or a concrete non-applicability reason; missing or uncertain units keep coverage incomplete. A batch size of 20 limits one packet, not the total rules considered. Reading a rule does not count as checking it. Evidence becomes stale after the code or catalog changes.

The review also runs appropriate project checks, repetition scanning and supported JS/TS AST plus CSS/SCSS checks. Findings must be introduced or materially worsened by the change; unrelated old code is context, not an automatic cleanup request. A rule's priority does not excuse skipping it and does not justify inflating its severity.

• FIX FIRST: verified P0/P1 findings need fixing.
• CLEAN-CODE FINDINGS: applicable P2 findings remain unresolved.
• INCOMPLETE: missing checks, unfinished packets, parser gaps or other coverage limits prevent a clean result. Coverage gaps are also reported alongside findings.
• READY: relevant review, exclusion audit and checks are complete, with no unresolved findings beyond justified exceptions.

The engine's RULE PASS COMPLETE describes the selected packets and required integration ledger; it is not the final READY verdict. A review is read-only and private. Ask separately to fix findings. After code changes the agent creates a fresh evidence plan. If a PR opening was requested together with the review, the workflow stops at the concrete review result for your response.

Project overview

Use $project-overview (or ask for /project-overview) for an occasional review of the whole product. It is explicitly invoked and does not run or fetch its catalog during ordinary coding or a pre-PR review.

$project-overview Review this project before launch. Identify missing user journeys,
privacy/accessibility checks, operational gaps and anything needing owner verification.

Browse the separate [Project Readiness page](https://coderuleset.com/project-readiness) or fetch [the complete JSON catalog](https://coderuleset.com/api/project-readiness). The initial catalog has 90 evidence-oriented checks across 25 areas: header, hero, footer, trust, licences, onboarding, forms, accounts, accessibility, privacy, cookies, commerce, recovery, mobile/performance, discovery, security, communication, operations, online stores, teams, bookings, user content, AI, children and localization. All 20 themes from the original legal checklist are represented with applicability and exceptions.

The agent establishes the product's features and markets, downloads a separate versioned snapshot and reviews every category in manageable packets. Unknown features remain candidates; a missing file does not prove a missing capability. Results are verified, missing, partial, needs-manual-verification or not-applicable, each supported by evidence. Missing and partial items receive next actions. Legal checks require current primary-source and jurisdiction verification; this is an EU/EEA starting point, not exhaustive global compliance advice.

Plans, profiles and reports stay privately under your home configuration, outside the reviewed repository. No project source or findings are uploaded to CodeRuleSet. The helper rejects stale repository/profile evidence, incomplete catalogs and unsupported decisions. External configuration and production behavior still need dated evidence. A completed ledger can contain unresolved findings and never implies a compliance certificate or launch approval. The review does not change code, publish findings, trigger payments or contact other people.

The installed skill contains reproducible commands for fetching, profiling, packet review, evidence recording and report export. Start a new Codex chat after updating the installer to discover $project-overview. Other coding agents can use the public catalog manually; this installer only installs the Codex skill.

Write a PR description

Use $pr-description separately. It reads the full diff and ticket context, then produces a suggested title and a copyable Markdown description. It reports only checks that actually ran. It does not automatically run a review, commit, push or publish a PR. A description can be drafted before review, with missing validation stated accurately.

Save rules and learn from feedback

Use $rulebook-author to explicitly save or improve a rule. Give a concrete trigger, the desired change and any legitimate exception. The agent checks overlap and preserves existing identity, priority and useful exceptions when editing a rule. Pure wording curation is not counted as a new violation.

Durable instructions must be recoverable on another computer or by another AI tool. Store reusable engineering and tracker/workflow rules in the central catalog, and agent-specific procedures in this repository's versioned setup guide and skills. Update existing owners instead of creating competing copies. Synchronize local configuration after saving the shared source; a local AGENTS.md edit alone is not sufficient. Verify the saved rule or source and state whether changes are remotely available. Keep credentials and private machine configuration out of shared instructions, and preserve the user's publication permissions.

For Jira work, the catalog rule acli-jira-read-task-create-branch requires matching the actual repository to the parent and relevant subtasks before choosing a key for a branch, commit or PR. Use the issue that owns the repository implementation, not automatically the first issue mentioned. An existing branch name or an earlier AI answer is not evidence of the correct key. This rule also applies when another AI tool reads the catalog without installing the Codex skills.

When you supply mentor or PR review feedback, $mine-pr-rules extracts reusable lessons, including small clean-code nits. It excludes praise, bot noise, author replies and product-only instructions, checks live overlap, runs a dry run, then processes the authorized feedback serially. Each comment gets a created, reinforced, improved, already-processed, skipped or error outcome. Uncertain writes must be reconciled before retrying. Your agent's unconfirmed findings are not mentor feedback.

Writing rules requires the existing private authoring configuration in the tooling repo, including DATABASE_URL; use your password manager to configure it locally. Do not paste credentials into chat or commit them. Some authoring operations and the web application need additional private configuration. The installer and normal Codex retrieval do not require it.

Automated review learning: web + Codex

Open [Review Learning](https://coderuleset.com/review-learning) and use Add organization to collect from all its active repositories once a week. Activity means a push within the configured window (90 days by default); archived, disabled and older repositories are excluded. Each weekly run reads the complete repository list visible to the server's GITHUB_TOKEN, updates the active selection, then collects inline comments, review summaries and PR discussions. Access to every intended private repository must be granted to that token. The activity data comes from GitHub's [organization repositories endpoint](https://docs.github.com/en/rest/repos/repos#list-organization-repositories).

New active repositories join automatically, and inactive repositories stop collection and Codex claims while retaining their comments and checkpoints. Repositories that become active again resume from their saved checkpoint. Connecting an organization takes over its existing repository schedules without erasing progress or author filters. Newly discovered repositories include all PR authors. Collection has a rolling 21-day limit based on when the comment was created, including on older PRs that receive new feedback. A later configured start date narrows the window further. Subsequent discoveries use the previous discovery checkpoint to avoid rescanning older PRs. The web shows active/accessible counts, the next weekly check and discovery errors. A failed or incomplete discovery preserves the previous selection and prevents collection for that organization until discovery succeeds. Automatic failures wait for the next scheduled interval (or longer if GitHub requires it); they do not retry every few minutes. Saving enabled organization settings requests a fresh activity check.

Use Add repository for individually managed sources outside connected organizations. Their interval defaults to one week and supports 15–10080 minutes. You can select PR authors and the earliest feedback date. Start dates default to 21 days ago. The rolling limit still applies when an earlier date is configured; editing an old comment does not make it eligible again. The server stores the queue privately and continues collecting while Codex is offline. Pausing an organization or individual repository stops collection and new Codex claims. Inactive and paused repositories are hidden by default; enable Show inactive and paused repositories to inspect their retained history.

Codex processes that queue with $review-learning, using the existing private DATABASE_URL in the pro-code checkout and Node.js 20.12 or newer. This uses your Codex plan rather than an AI API call from the website. No new API key or public write endpoint is needed. Source files and authoring exports stay under the home configuration's state/review-learning directory. Global AGENTS.md advertises this capability independently of rule loading; ordinary coding and rule fetching do not import feedback automatically.

Ask Codex to schedule $review-learning in the current chat once a week after the web collection, process at most three comments per run, preserve your chosen quota reserve, and stay quiet unless rules change, a run fails or your input is needed. The computer and desktop app must be running for local processing. See [scheduled tasks](https://learn.chatgpt.com/docs/automations?surface=app). The installer supplies the skill and awareness, but does not create a duplicate schedule. On a new computer, restore private authoring configuration and create the schedule explicitly. Check the web page's Codex connection timestamp to verify that a worker has connected; it does not prove a desktop schedule is enabled.

Each comment has a stable source identity and a content fingerprint. An unchanged ID/body is not queued again. Each repository also records successfully scanned PR versions; unchanged discussions are skipped, while new activity on the same PR can still bring new comments. A PR checkpoint advances only after every feedback page has been saved, so interrupted runs resume safely. The run history shows new/changed comments, duplicate comments and unchanged PRs skipped.

Central processing receipts are checked before Codex claims work, including receipts written by the manual ingest path. Previously imported content with edits or missing content hashes is held for reconciliation. Pending feedback that ages beyond 21 days is skipped with a reason; completed learning history remains intact. Old Claude corpus files prove fetching, not successful ingestion, and are never blindly marked processed. Legacy records without source IDs still require provenance/context checks.

A claim lasts 45 minutes, interrupted claims can be reclaimed, and three interrupted attempts move the item to manual review. New rules, deliberate improvements, repeat counts and source receipts commit together. The updated manual ingest and this queue share central receipts for new source IDs. Legacy imports without IDs need provenance checks. Changed sources or concurrently edited rules cannot silently overwrite the original result. Repeat frequency alone does not raise severity in the new queue workflow; existing manual-ingest escalation behavior remains unchanged.

The inbox shows pending, processing, created, reinforced, improved, skipped and needs-review outcomes. Retry held comments from the web after resolving missing context. Comments that already changed a rule require deliberate reconciliation instead of another violation. Collection errors retain checkpoints and appear in run history. For local previews or builds, set REVIEW_LEARNING_AUTO_COLLECT=off and PACKAGES_AUTO_REFRESH=off. The worker also skips the production-build phase.

Inspect subjects and coverage

These commands are for inspecting the workflow, not prerequisites for everyday use. Run them inside the current Codex session after its one initial fetch:

python3 ~/.codex/skills/rulebook-loader/scripts/review_rules.py inventory
python3 ~/.codex/skills/rulebook-loader/scripts/review_rules.py search --subject styles --query 'layout overflow' --limit 20
python3 ~/.codex/skills/rulebook-loader/scripts/review_rules.py search --subject functions --query 'parameters naming' --limit 20

Use --offset to paginate a subject and show --rule RULE_ID for the full card. Explicit review plans, exclusion audits and evidence commands are documented in the installed rulebook-loader/references/segmented-review.md. Generated catalogs, plans and receipts stay under your home configuration.

Update or troubleshoot

Update the tooling checkout after accounting for local edits, run pnpm install --frozen-lockfile, and rerun python3 scripts/setup-codex.py with the same options as your first installation. Existing files that need replacement are backed up. Review any personal skill changes before upgrading. Start a new chat so skill discovery and the snapshot reflect the update.

• Missing CODEX_THREAD_ID: run within Codex. For a deliberate external session, use a unique RULEBOOK_SESSION_KEY; never share a generic cache across sessions.
• Initial fetch failure: report it and retry only as authorized. Invalid responses are not installed; a failed explicit refresh preserves the previous valid snapshot.
• Missing reviewSource: the server or cached snapshot is older. Reduced metadata stays visible; use a new chat or explicitly request refresh when appropriate.
• AST dependency failure: install dependencies in the tooling checkout. RULEBOOK_REPO can override its remembered location. Do not install personal tooling inside the reviewed company repo.
• Stale evidence: recapture the current diff and create a new plan. Do not reuse a clean verdict from older code.

What is implemented, and what remains

The September 2026 rollout classified all 2,594 snapshot rules into 28 overlapping subjects without deleting rules. Classification is derived from source metadata and text signals; every actual application still needs context and exception checks.

The follow-up semantically reviewed and updated 400 rules, preserving every rule identity and priority. Applicability, rationale, exceptions, examples and existing Croatian explanations were corrected. Concrete fixes include React version differences, misleading type assertions, null/zero handling, cache concurrency and CSS cascade assumptions. 2,194 rules still need this semantic pass. The complete inventory and reviewable changes are versioned under rule-curation/ in the tooling checkout.

Quality flags remain on 2,112 rules, down from 2,373 at the first rollout. A flag is a curation candidate, not proof that a rule is wrong; a reviewed rule can still carry a conservative scope flag. Removing a flag is not equivalent to verifying meaning.

There are now 17 deterministic candidate checks: 12 for JS/TS and five for CSS/SCSS. They cover small expression/type/JSX improvements and selected stylesheet patterns, including unitless line-height candidates, zero units, radius shorthand, broad transitions and duplicate declarations. They report parser gaps, require context and never auto-fix code. Other languages retain conservative profiling and contextual review; existing repository checks remain necessary.

Real feedback was evaluated against 19 frozen source cases. At 11 specifically labeled detector targets, the original checks found eight and the expanded checks found 11. Seven other cases require contextual judgment, one guards against a particular false alarm, and findings outside labeled locations remain unadjudicated. A separate targeted review recorded predictions before opening the chosen PR comments and exposed missed consumer/configuration concerns, which led to the integration audit. This is useful regression evidence, not a general AI accuracy or precision score. Private source and PR evidence stay outside the repository.

The 30 synthetic retrieval scenarios still verify rule selection separately. See rule-curation/README.md for the evaluation protocol, limitations and safe curation commands. Large packets can require substantial review time; unfinished coverage must remain visible.

Legacy Claude setup

The existing Claude commands and semantic retrieval remain available separately. They do not yet use the new Codex segmented evidence engine. Installing the Codex bundle does not update Claude.

For the legacy workflow, follow scripts/setup-claude.sh and claude-setup/ in the repository. Configure its private .env values first and have Node, pnpm, Git and GitHub CLI available. It installs ~/.claude commands and builds embeddings/triggers. Embeddings run locally, but selected full rules are read from remote Postgres and the model may be downloaded. This workflow is not wholly offline.

After confirmed rule changes, legacy Claude retrieval may need node scripts/embed-rules.mjs followed by node scripts/derive-triggers.mjs from the tooling repo. Codex does not use those artifacts.

Service integrations

Open [Integrations](https://coderuleset.com/integrations) to keep project service connections centrally and give an agent access to detailed, paginated API reports. This is separate from coding rules, Repository Knowledge and Review Learning. Installing or loading those workflows does not fetch analytics or start SEO work.

Server setup

Set INTEGRATIONS_ENCRYPTION_KEY to a cryptographically random 32-byte key encoded as 64 hexadecimal characters in the production server's secret environment, then redeploy. Generate it privately, for example with openssl rand -hex 32 in your own terminal. Do not paste it into an AI chat, Git, client environment variables or the database. The UI remains locked until it is configured. Set APP_BASE_URL=https://coderuleset.com to make the management API's origin check explicit behind the reverse proxy.

Back up this encryption key in a password manager separately from the database backup. Provider secrets and report payloads use AES-256-GCM with owner/connection-bound authenticated context. Replacing the key without re-encrypting saved rows makes them unreadable; there is no automatic key rotation or recovery. Removing a connection deletes its encrypted credentials and cached reports. Provider-side tokens must be revoked at the provider when no longer needed. Database backups may retain earlier ciphertext according to the backup policy.

The database role needs permission to create the integration_* tables on first use. Management requires the existing allowed Google login and matching same-origin POST. The agent API accepts only scoped bearer tokens. Tokens are hashed in storage, limited to selected existing connections, expire after 1–90 days and can be revoked individually. Removing an allowed login also disables its agent tokens. Access metadata is retained for 90 days, without credential or report payload logging.

Detailed reporting and SEO diagnostics

The version 2 agent endpoint defaults to 1,000 rows per page and returns pagination.next (offset or opaque cursor), returned count, optional provider total and an explicit coverage statement. Request options.limit up to 25,000; provider page maxima still apply. Report variants, filters, targeting and pagination have separate encrypted cache keys. The web report has a Load more results button.

Use the installed helper's report ... --all --output /absolute/private/report.json or keywords ... --all --output ... to collect available pages without flooding chat. --max-pages defaults to 100 and can reach 1,000, with an additional one-million-row collection budget. Partial failures and exhausted budgets preserve rows and the continuation. A complete collection means available pagination ended, not that Google exposes anonymized queries or that other provider restrictions disappear. Overview reads every permitted connection for the exact project; Ads still requires explicit seed keywords.

report --kind url-inspection --url ... uses the existing read-only GSC consent and is limited to its property's URL boundary. It reports the indexed version, not a live test or indexing submission. --kind crux requires server-only INTEGRATIONS_CRUX_API_KEY with Chrome UX Report API enabled; --scope origin explicitly selects domain-level field data when a URL lacks sufficient samples. --kind pagespeed returns Lighthouse lab category scores and every audit summary, with optional INTEGRATIONS_PAGESPEED_API_KEY. Enable PageSpeed Insights API for that key. These server keys never enter agent configuration. Diagnostics are on-demand only; no Google API enablement or deployment is performed by installing the skill.

Detailed reports use the existing encrypted keyed-cache table without a schema migration. Most variants cache for one hour; Ads, Clarity, CrUX and PageSpeed for 24 hours. Diagnostic failures have their own variant cooldown and do not block GSC traffic reports. Clarity has ten provider calls per project/day; dimension variants consume separate calls. Read the versioned service-integrations skill for supported dimensions and command examples.

Connect services

Choose a service, a project name/domain and a connection label. Enter credentials only in the signed-in web form. The form shows the identifiers and scopes required for that provider. For Google, choose Connect Google, approve access and select the resource. Advanced: enter credentials manually remains available. Save, then select Get report (or Keyword Planner for Ads) to test actual access. Saving alone does not prove a credential works. Editing accepts blank secret fields to keep existing secrets; ordinary configuration fields must be filled in again as shown. Changing the project or provider identifiers removes the connection from existing agent grants, so access must be granted with a new token. Rotating only a secret preserves grants.

• GitHub: Paginated open PR metadata in one repository. Fine-grained token with Pull requests: read.
• Search Console: Paginated queries/pages, countries/devices/dates, independent totals, filters, custom dates and URL Inspection. OAuth client ID/secret and refresh token with webmasters.readonly; exact property.
• Google Analytics: Paginated pages, sources, events, countries/devices, custom dates and independent totals, including engagement and key events. OAuth credentials with analytics.readonly; numeric property ID.
• Google Ads: Keyword Planner ideas and historical metrics for up to 20 seed keywords. Approve adwords, select a login account, then an advertiser account. The OAuth client's Google Cloud project needs Basic access, or Standard access permitting keyword research; Explorer does not include planning. Developer tokens are no longer required. No campaigns or ads are created or changed. See [Google Ads access levels](https://developers.google.com/google-ads/api/docs/api-policy/access-levels).
• Google APIs & Services: Paginated enabled APIs in one Cloud project. OAuth credentials with cloud-platform.read-only, project number and Service Usage Viewer.
• Clarity: All returned records and dimensions from the last 72 hours, up to the provider's 1,000 source-row cap; no provider pagination. Project Data Export token.
• Sentry: Paginated unresolved issue summaries in one project. event:read token, organization/project slug and regional host.
• Fastmail: Paginated mailbox names, hierarchy, roles, email and thread counts. JMAP token with mail access; optional account ID.
• Twilio: Paginated usage categories and their costs. Prefer an API key allowed to read usage. An existing Account SID and Auth Token is also supported. Enter either the API key pair or the account auth token; a supplied key SID takes precedence and the unused secret is discarded. Account auth tokens have broader access at Twilio, but this app only reads usage records.
• Umami: Traffic totals and paginated pages, sources, countries, devices and events. API token, website UUID and API base URL.

Google services now use Connect Google. The server reuses GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET and the existing registered /api/auth/google/callback URL (or GOOGLE_REDIRECT_URI); no additional callback registration is needed when sign-in already uses this app. Keep APP_BASE_URL set. Add the service scopes to the OAuth consent configuration and enable the APIs in the OAuth client’s Cloud project: Analytics Admin API + Analytics Data API, Google Search Console API, Google Ads API, or Cloud Resource Manager API + Service Usage API. These Google-side prerequisites are not enabled by deploying CodeRuleSet. The account still needs permission for each selected resource.

If another Cloud project already has Google Ads Basic access, configure its Web application OAuth client as the server-only GOOGLE_ADS_CLIENT_ID and GOOGLE_ADS_CLIENT_SECRET. Set both together; a partial pair blocks Ads authorization rather than mixing clients. Add CodeRuleSet's exact callback URL (normally https://coderuleset.com/api/auth/google/callback) to that client's Authorized redirect URIs. This override applies only to new Ads authorizations; sign-in and the other Google services keep the default client. Existing Ads connections require Edit → Connect Google to switch clients. Each pending flow retains the client pair with which it started. Desktop clients with localhost callbacks cannot be used for this web redirect.

Choose a service, project and label, then Connect Google. Google requests only that service’s scope and offline access. After approval, choose a GA4 property, Search Console property, Cloud project or Ads login/advertiser account and save. The callback checks the signed-in owner, browser state, one-time state and PKCE. Temporary credentials are encrypted and expire after 15 minutes; starting a new connection replaces that owner’s unfinished flow. Tokens stay on the server. Your CodeRuleSet login alone does not grant service access. A cancelled or expired flow can be started again without changing your existing connection.

Google retired Ads developer tokens on September 9, 2026; access levels now belong to the OAuth client's Cloud project. CodeRuleSet does not request or send these tokens. Previously saved tokens are ignored and removed when the connection is saved again. See [Google's migration guide](https://developers.google.com/google-ads/api/docs/api-policy/developer-token).

For Keyword Planner, enable Google Ads API, then open the [Google Ads API Overview](https://console.cloud.google.com/google/ads-apis/overview) for the project that owns the OAuth client. New projects start with Test access. Apply for Explorer, complete Brand verification, then apply for Basic access. Explorer allows account discovery but excludes keyword planning. Existing Standard access must permit keyword research. Enabling the API alone does not approve production Keyword Planner access.

Each connection has a Reconnect button. For Google it opens consent directly and preselects the existing resource when available. For other providers it opens the saved connection form for replacement credentials. Keep the same project and resource to preserve agent grants. After saving, request a report to verify access. Connection status records the latest provider request and distinguishes expired authorization, denied permissions, quota limits and other failures. Cached reports do not overwrite a newer failure. Diagnostic errors remain separate from the main connection status.

Google OAuth apps with an external audience and publishing status Testing issue refresh tokens that expire after seven days for these service scopes. To avoid this testing limit, the operator must configure the appropriate OAuth project for production and meet Google's verification requirements, then reconnect affected services. Ads may use a separate OAuth project. Revocation and provider policies can still invalidate production tokens. See [Google's token expiration documentation](https://developers.google.com/identity/protocols/oauth2#expiration). Prefer read-only provider roles. The adwords scope itself permits broader actions at Google, while CodeRuleSet exposes only fixed account-discovery and keyword-research requests.

Recent access shows connection names and safe failure explanations. It groups repeated results from the same connection and agent within each hour, with a request count and filters for connection or errors. It summarizes the latest 200 audit events without discarding the underlying 90-day audit history. Existing events recorded before error details were added retain their original outcome codes.

Select Keyword Planner, enter up to 20 keywords, choose ideas or historical volume, language and location IDs. Croatian (1039) and Croatia (2191) are defaults; use the actual target market. Reports show available average/monthly searches, advertiser competition and top-of-page bid ranges. Competition is not organic SEO difficulty, unavailable metrics are not zero and close variants may be combined. Google determines the available historical months, usually the last 12; the traffic 7/28-day selector does not apply.

Umami Cloud uses https://api.umami.is/v1. For self-hosted Umami, the operator must add the exact trusted HTTPS API base, such as https://analytics.example.com/api, to comma-separated INTEGRATIONS_UMAMI_BASE_URLS. Only allow instances you control, never internal infrastructure or user-controlled redirect/proxy endpoints. Outbound redirects are rejected. Sentry supports sentry.io, us.sentry.io and de.sentry.io; self-hosted Sentry and alternative Fastmail API hosts are not currently supported.

The GitHub connection is independent of the existing Review Learning collector; it does not reuse or widen that collector's company credentials. It currently reports PR metadata, not source files, checks or review discussions. Fastmail does not read message contents or send mail. Cloud does not list API keys, billing or infrastructure. No adapter changes ads, sends SMS, writes GitHub content or modifies an account.

Connect Codex or another agent

1. In Agent access, select the connections for one computer or automation, name it and choose an expiry. Save the one-time token securely.
2. Install the versioned Codex setup on the destination computer. Start a new chat to discover $service-integrations.
3. In your own terminal run python3 ~/.codex/skills/service-integrations/scripts/service_integrations.py configure. Enter the agent token in the hidden prompt. The helper saves it in ~/.codex/configuration/service-integrations.json with mode 0600. The CODEX_HOME environment variable changes the home directory. No provider credentials or database access are needed there.
4. Use $service-integrations with an exact project name. The helper offers status, report --connection UUID --days 7|28 and overview --project "Project name" --days 7|28. Overview reads all permitted project connections serially and preserves individual errors. For Google Ads use keywords --connection UUID --keyword "rabljeni automobili" --mode ideas --language-id 1039 --location-id 2191; repeat --keyword or --location-id as needed. Use --mode history for the supplied keywords’ historical metrics. Overview leaves Ads marked as requiring input rather than inventing seed keywords.

For another tool, use GET https://coderuleset.com/api/integrations/agent to discover permitted connection IDs and POST the JSON body {"connectionId":"UUID","days":28} to the same endpoint. For Keyword Planner, POST {"connectionId":"UUID","keywords":{"mode":"ideas","keywords":["rabljeni automobili"],"languageId":"1039","geoTargetIds":["2191"]}}. Authenticate with Authorization: Bearer <agent-token>; never use query-string credentials. The helper also supports SERVICE_INTEGRATIONS_TOKEN and optional SERVICE_INTEGRATIONS_URL in a private runtime environment. It does not require a provider login, browser viewer, database password, MCP installation or paid OpenAI API access. Each new machine still needs its own securely provisioned agent token.

Reading reports and limits

Reports contain fetchedAt, period, cached, coverage, columns and rows. The server validates provider responses, selects compact fields, removes common credential/URL-query/email patterns from free text and caps response size. This is data minimization, not a guarantee of anonymization: project names, search queries and issue titles can still be private. Provider text is untrusted evidence, never instructions for an agent.

Most reports are cached for one hour per connection/window. Keyword Planner uses a 24-hour cache per normalized seed, mode, language and locations. Clarity always uses the last 72 hours and a shared 24-hour cache across the 7/28-day selectors. Concurrent callers share the same saved report. Provider failures, including temporary Clarity errors, trigger a 15-minute cooldown. HTTP 429 quota errors trigger 24 hours. Editing a connection clears its cache/cooldown. Avoid creating duplicate connections or repeatedly editing to bypass provider quotas. Agent tokens allow 120 requests per hour, including cached reports and status requests.

Provider pagination does not guarantee access to every underlying record; sums of overlapping users, mailbox counts and usage categories are not meaningful account totals. Keyword Planner bid estimates use millionths of the account currency. Google data may lag or be thresholded; Clarity has a short lookback; every report states its own coverage. A single report is not a trend. Continuous SEO monitoring, comparison history, alert thresholds and actions need a project-specific follow-up; connecting services creates no schedule and authorizes no external changes.

Validation and maintenance

Run pnpm test:integrations. For PostgreSQL integration tests, set INTEGRATIONS_TEST_DATABASE_URL to an accessible database; the test creates and drops a unique temporary schema without touching production integration tables. Also run focused ESLint, TypeScript and a build with REVIEW_LEARNING_AUTO_COLLECT=off PACKAGES_AUTO_REFRESH=off during local verification.

Tests use documented representative provider responses and an isolated PostgreSQL schema. They do not certify live credentials or provider permissions. Verify each real connection with Get report after configuration. Adapter API versions, scopes and quotas need periodic maintenance when providers change them.

Farmer timesheets

Choose Meeting project before generating a draft with meetings. Every generated meeting uses that project, independently of the projects inferred from commits. In the draft, use Select all meetings, Select by task, or individual checkboxes, then choose Apply project and/or Apply task. Bulk edits preserve durations and descriptions and reject incompatible project/task combinations before changing any row. They update the draft only. Push to Farmer remains a separate confirmation.

Open Farmer in the navigation and click Connect Farmer. Open the approval link and confirm the displayed code with your Profico account. This uses Farmer's device authorization protocol, as Highlight does. CodeRuleSet stores its own encrypted session on the server; it does not copy Highlight's system-keychain session. The server needs the same INTEGRATIONS_ENCRYPTION_KEY used by Integrations, and PostgreSQL. No Farmer CLI installation or provider secret in the browser is required.

Generate a draft for up to 62 days, review every project, task, description and duration, then explicitly confirm Push to Farmer. Drafts use the existing company-only GitHub and Jira sources. Generation may call Gemini when configured; FARMER_GEMINI_MODEL selects its model. No scheduled generation or automatic submission is started.

Farmer projects and tasks come from the live Profico catalogue. Durations use 15-minute steps, Break has no project, and absences use Farmer's dedicated absence operation and must match the scheduled working day. Generation skips populated dates, and submission checks again under a lock. Existing Farmer entries are never deleted or replaced. After any submission attempt, generate a fresh draft before sending more; if a request failed, check partially filled days in Farmer first because a timed-out write may have succeeded.

Disconnect from CodeRuleSet removes the saved web connection and pending approval. It leaves your Farmer entries and Highlight session intact. Revoke a device session in Farmer itself if needed. The old /harvest bookmark redirects to Farmer; old Harvest API routes have been removed. Harvest credentials are no longer used. Packages uses its own optional PACKAGES_GEMINI_MODEL setting.