Run this inside the Rails repo you want to understand.

You are auditing an existing Ruby on Rails application for architectural coherence and for the quality of the context it gives coding agents.

This is a diagnosis-only pass. Do not modify files. Do not install gems or packages. Do not run migrations, seed data, destructive commands, or anything that changes persistent state. You may inspect the repository, schema, routes, configuration, tests, and safe local runtime state if the application is already set up. Do not contact production services or external APIs.

The goal is NOT to make this application look like Rails Baseline or any other starter kit. Different architectural choices are fine when they are coherent, deliberate, safe, and discoverable. CanCanCan is not a problem because another app uses Pundit. Sidekiq is not a problem because another app uses Solid Queue. React is not a problem because another app prefers Hotwire.

Your job is to answer this question:

How clearly does this repository teach a coding agent how this application is supposed to work, where does that precedent conflict with itself, what important decisions are missing or implicit, and which findings represent actual correctness or security risk rather than stylistic preference?

WORK IN THREE PASSES

PASS 1: INVENTORY BEFORE JUDGMENT
First map the repository without forming conclusions. Identify the Rails version, major gems, authentication, tenancy/account model, authorization approach, billing if present, background jobs, integrations, frontend approach, deployment path, tests, and agent/developer documentation.

Inspect the closest equivalents of:
- README and contributor/setup documentation
- AGENTS.md, Agents.md, CLAUDE.md, .cursor rules, or other coding-agent instructions
- architecture/design/decision documents
- current product or engineering docs that appear authoritative
- Gemfile and lockfile
- config/application.rb, environment configuration, initializers, credentials references, and feature configuration
- config/routes.rb
- db/schema.rb or db/structure.sql, plus important migrations when schema intent is unclear
- app/models, controllers, policies/authorization code, jobs, mailers, channels, helpers, components, services/operations, queries, and concerns as applicable
- lib/ when it contains application architecture rather than generic utilities
- test/ or spec/, especially integration/request/system tests around architectural boundaries
- deployment and operations files such as Dockerfile, Kamal config, Procfiles, CI workflows, queue/cache/cable config, health checks, and observability setup

Do not treat every document as equally authoritative. Separate current operating instructions and architecture docs from old plans, backlogs, launch checklists, generated notes, experiments, and historical migration documents. Historical documents are useful evidence of intent, but they should not overrule current working code and tests.

PASS 2: TRACE BEFORE CLASSIFYING
When something looks suspicious, inspect enough nearby code and call sites to understand its context before calling it a problem.

Important rules:
- Do not infer an architectural pattern from one file or one search result when broader precedent is available.
- Do not call duplicated code conflicting precedent until you check whether one path is explicitly legacy, deprecated, transitional, provider-specific, admin-only, or intentionally compatibility code.
- Do not call an endpoint unauthorized until you inspect inherited/base-controller protections, shared concerns, routing constraints, and comparable tests.
- Do not call a global Model.find or Model.find_by a tenancy bug merely because it is global. Context matters.
  - Request-facing code using user-controlled identifiers should normally prove tenant/user access through an accessible scope or an equivalent authorization check.
  - Admin code may legitimately query globally when the admin boundary is real and consistently enforced.
  - Signed webhook/provider callbacks may legitimately map a provider identifier globally after authenticity is verified.
  - Background jobs may legitimately load records globally by database ID when those IDs came from trusted application state. If multiple tenant-owned records are combined, verify their relationship rather than assuming the ID itself is unsafe.
- Internal database IDs are not inherently a defect in jobs, admin tooling, or internal associations. Public identifiers matter primarily at untrusted external boundaries such as user-facing URLs, APIs, shared links, exports, and support-facing references.
- Background jobs do not need to recreate a specific Current-account pattern. Explicit account/user IDs, scoped associations, or another clear mechanism are fine if the job re-establishes the required ownership context.
- Global recurring iteration is not automatically unsafe. Verify that each unit of work scopes subsequent reads and side effects correctly.
- Search call sites before claiming that a helper or model method causes provider network traffic during ordinary page rendering.
- Reversibly encrypted OAuth access tokens, refresh tokens, Slack bot tokens, and similar credentials may need to be retrieved to call the provider. That is different from verifier-only secrets such as API keys or reset tokens, which often should be stored as digests when plaintext recovery is unnecessary.
- A product-specific workflow is not automatically a missing abstraction.

PASS 3: REPORT ONLY MATERIAL FINDINGS
The architecture map should cover the whole application, but the detailed findings should be selective. Do not turn the report into a dump of every small inconsistency you can find. Prefer roughly 10 to 15 material findings total across coherent patterns, conflicts, blind spots, and risks. Include fewer if the repository is already coherent.

If evidence is incomplete, lower the confidence instead of filling gaps with assumptions. If an area is genuinely irrelevant to the product, mark it Not applicable. If the code does not give you enough evidence, mark it Unknown and say what would resolve the uncertainty.

Prefer evidence from working code and tests over comments that may be stale. Documentation still matters because this audit is partly about what an agent can discover. Call out disagreements between current docs and implementation instead of silently choosing one.

AUDIT AREAS

1. APPLICATION SHAPE AND RAILS CONVENTIONS
- What Rails version and major framework choices are in use?
- Is the application mostly conventional Rails or does it have important custom layers, engines, DSLs, base classes, command buses, repository abstractions, or metaprogramming an agent must understand first?
- Where does domain behavior normally live: models, POROs/services, operations, commands, queries, concerns, something else?
- Are there multiple competing homes for materially similar behavior?
- When adding a normal resource or workflow, is there an obvious nearby implementation to imitate?

2. IDENTITY AND AUTHENTICATION
- What establishes user identity?
- How are registration, login, logout, confirmation/verification, password recovery, sessions, and optional social login handled?
- Does identity creation also create domain/tenant state? If so, is that intentional and consistent across normal signup and invitation flows?
- Are authentication concerns mixed with account membership, authorization, billing, or product capability checks?
- Are sensitive authentication endpoints deliberately abuse-aware where the product needs that protection?

3. TENANCY, ACCOUNTS, AND DATA ISOLATION
- Is the app single-tenant, multi-tenant, organization/account/workspace based, or something else?
- What record or concept is the tenant boundary?
- How does a request establish current tenant context?
- How are memberships/roles represented?
- How are tenant-owned records queried from request-facing code?
- Can request-supplied tenant or resource IDs accidentally become proof of access?
- Are there default scopes or implicit globals that make tenant behavior difficult to reason about?
- How do background jobs and recurring work re-establish the ownership context they actually need?
- Look for negative cross-tenant tests. If tenancy is important and these are absent, call that out.

4. AUTHORIZATION
- What decides whether the current user may perform an action?
- Is authorization centralized through a clear mechanism or scattered through controllers, views, models, and services?
- Are collection scopes handled consistently?
- Does authorization ever broaden a tenant scope instead of narrowing an already-safe relation?
- Are account roles, system/admin privileges, ownership, billing access, and product entitlements accidentally collapsed into one boolean concept?
- Identify entry points that appear to lack authorization only after checking inherited protections and equivalent flows.

5. BILLING, PRODUCT ACCESS, ENTITLEMENTS, AND LIMITS
Only evaluate this section if the application has paid plans, subscriptions, paid features, quotas, usage, or other commercial access rules.
- What provider/gem owns payment lifecycle?
- What application-owned code decides whether a customer may use a feature?
- Does ordinary product code branch directly on provider objects, price IDs, subscription IDs, or webhook payload state?
- Are boolean capabilities and quantitative limits represented clearly?
- Is there one place that maps provider state to stable product concepts, or many ad hoc checks?
- After tracing call sites, do ordinary page renders make provider network calls?
- How are missed/delayed webhook events reconciled?
- Are billing capability checks and user authorization tested independently where both matter?

6. PUBLIC IDENTIFIERS AND EXTERNAL IDENTITY
- Which records cross untrusted or externally visible boundaries such as user-facing URLs, APIs, shared links, exports, support references, or provider callbacks?
- Does the application expose sequential database IDs at those boundaries where that appears accidental?
- If it uses UUIDs, slugs, public IDs, signed IDs, or another strategy, is the choice consistent and indexed appropriately?
- Are public identifiers ever mistaken for authorization or tenant isolation?
- Do routing conventions agree with model naming, polymorphic routes, and parameter lookup conventions?
- Treat internal job arguments, database associations, and protected admin screens separately from public identity.

7. BACKGROUND JOBS, SCHEDULING, AND RECURRING WORK
- What queue system is used and what belongs in jobs?
- Do jobs carry identifiers and inputs that can be safely reloaded later rather than request-local assumptions?
- Is tenant/user ownership context re-established deliberately where it matters?
- When a job combines multiple records, does it verify the expected relationship between them?
- Are retries safe for side effects?
- Are jobs idempotent where duplicate execution is realistic?
- How is recurring work scheduled, and does each unit of recurring work scope later reads and side effects correctly?
- Are failure reporting and dead/failed job inspection discoverable?

8. EXTERNAL INTEGRATIONS, WEBHOOKS, AND OUTBOUND HTTP
Only evaluate what exists.
- Where are provider clients and external boundaries owned?
- Are retrievable provider credentials encrypted appropriately and filtered from logs?
- Are verifier-only secrets stored so plaintext recovery is avoided when it is unnecessary?
- Do outbound HTTP calls use explicit timeouts and sensible failure behavior?
- If destinations can be user-controlled, is SSRF/address validation handled deliberately?
- For webhooks: is signature verification performed against the correct/raw body where required, before business processing?
- Are webhook ingestion and processing idempotent and retry-safe?
- Is deduplication explicit?
- Are provider-specific details prevented from leaking throughout ordinary product code when a stable local boundary would be clearer?

9. ADMINISTRATION AND SENSITIVE OPERATIONS
- How is system-wide administration distinguished from tenant/account administration?
- Are admin entry points consistently protected through base controllers, constraints, or another clear boundary?
- Are especially sensitive lifecycle actions audited or otherwise traceable?
- Is impersonation present? If so, is it explicit, logged, reversible, and clearly separated from ordinary identity?
- Are operational UIs such as job dashboards or internal diagnostics exposed behind appropriate access controls?

10. FRONTEND OWNERSHIP
- What is the default rendering model: server-rendered Rails, Hotwire, React/Vue/etc., SPA, hybrid islands, or something else?
- Is it clear which layer owns routing, authentication state, forms, navigation, server state, and client-heavy interactions?
- Are there multiple frontend patterns for the same type of interaction without a clear reason?
- When client-heavy UI exists, does it have an obvious integration boundary with Rails?
- Do current docs and code agree about the default frontend approach?

11. OBSERVABILITY, ERRORS, AND OPERATIONS
- How are unexpected exceptions surfaced? Look for rescued exceptions that are only logged and then swallowed, but inspect the caller before deciding that behavior is wrong.
- Is there an application-wide error-reporting boundary or provider integration?
- Are request IDs, job IDs, tenant/account IDs, or useful tags available for tracing behavior without leaking secrets?
- Are health checks present and appropriate for the deployment platform?
- Can maintainers inspect background jobs and operational state?
- Are important external failures translated/reported consistently?

12. SECURITY DEFAULTS
- Distinguish retrievable provider credentials from verifier-only secrets before judging their storage strategy.
- Look for sensitive values in logs and unfiltered parameters.
- Review redirect handling where destinations can come from user input.
- Review content security policy and places where it has been broadly disabled to support a provider.
- Review public/abuse-prone endpoints for rate limiting where appropriate.
- Review tenant isolation and authorization ordering in request-facing code.
- Review file/upload behavior, generated artifacts, and download authorization if present.
- Separate concrete risk from generic hardening advice. Do not dump a generic security checklist into the report unless the repository gives evidence for it.

13. TESTING AND ARCHITECTURAL PROOF
- What test framework and testing layers are used?
- Which architectural boundaries have direct tests: authentication, tenancy, authorization, entitlements, jobs, external integrations, admin access, routing, deployment assumptions?
- Are there negative tests for cross-tenant access and denied authorization?
- Are provider boundaries stubbed cleanly?
- Do system/integration tests prove important user flows without being the only place domain rules are tested?
- Identify important invariants that appear to exist only by convention and have no test or current documentation support.
- You may inspect tests without running them. Run targeted tests only if the local environment is already set up, the test is safe, and execution would materially resolve uncertainty.

14. DEPLOYMENT, CONFIGURATION, AND ENVIRONMENT ASSUMPTIONS
- What is the supported deployment path?
- Are web/worker/scheduler roles clear?
- How are database, queue, cache, cable, object storage, and external services configured?
- Are production-only assumptions hidden in developer machines or vice versa?
- Is configuration split sensibly between build-time customization, runtime environment, and product policy?
- Are CI, lint, dependency/security checks, and deployment configuration consistent with the app's current architecture?

15. AGENT AND HUMAN CONTEXT
- What would a fresh coding agent read first today?
- Are there agent instructions, architecture docs, contracts, recipes, or other current guidance, or does the agent have to reverse-engineer everything from code?
- Which docs are current operating guidance and which are historical plans or stale artifacts?
- Where is strong precedent available in code but undocumented?
- Where is documentation clear but the implementation has drifted?
- Where are multiple equally plausible examples that would make an agent choose inconsistently?
- Are generated artifacts, uncommon capabilities, or sharp edges better explained as a bounded recipe than represented by fake/sample runtime code?

CLASSIFY EVERY MATERIAL FINDING INTO ONE OF THESE TYPES

A. COHERENT / PRESERVE
The app has a clear, working pattern. Different from your preference is not a defect. Say what the pattern is and point to the strongest evidence an agent should follow.

B. CONFLICTING PRECEDENT
The app solves materially similar problems in multiple live ways and a new agent could reasonably choose the wrong precedent. Show the competing examples. Before using this classification, rule out an intentional legacy, migration, compatibility, admin-only, or provider-specific path.

C. MISSING OR IMPLICIT DECISION
The app has not yet needed to make a decision, or the decision is so implicit that an agent would have to invent it when the next feature touches the area. Do not demand speculative abstractions. Explain when the decision actually needs to be made.

D. STRUCTURAL / SECURITY RISK
There is evidence of a correctness, isolation, authorization, secret-handling, retry/idempotency, unsafe external-call, or operational problem that should be addressed deliberately. State the concrete failure mode and how the repository evidence supports it.

E. PRODUCT-SPECIFIC / LEAVE UNGENERALIZED
The behavior is specific to this product and should not be turned into a broad application abstraction merely for consistency. Explain why.

For each detailed finding include:
- classification
- confidence: high / medium / low
- concrete evidence with file paths and important classes/methods/symbols
- enough call-site or surrounding evidence to show the finding is not based on a search hit alone
- why it matters to a human maintainer and to a coding agent
- the smallest reasonable next action, which may be "leave it alone"

Do not recommend a rewrite. Do not recommend replacing libraries simply to match fashionable defaults. Prefer documenting a good existing architecture over changing it. Prefer consolidating contradictory precedent opportunistically when the affected area is next touched, unless the contradiction creates an immediate correctness or security problem. Rank security, tenant isolation, authorization, data integrity, idempotency, and recoverability above stylistic consistency.

OUTPUT THE REPORT IN THIS ORDER

1. EXECUTIVE SUMMARY
At most 8 bullets. Include the strongest existing architectural qualities, the highest-risk findings, and the biggest places where an agent currently has to guess.

2. ARCHITECTURE MAP
A table with columns: Area | Observed pattern | Status | Confidence | Best evidence.
Keep each cell concise. Use the 15 areas above, marking irrelevant areas Not applicable and genuinely uncertain areas Unknown.

3. COHERENT PATTERNS WORTH PRESERVING
List the strongest local precedents a coding agent should imitate. Include file paths. Prefer a few strong patterns over exhaustive praise.

4. CONFLICTING PRECEDENT
For each material conflict, show the competing live patterns, evidence, likely canonical direction if knowable, and whether to fix now or only when touched. Do not include clearly bounded legacy or compatibility paths unless their status is itself unclear to a new agent.

5. AGENT BLIND SPOTS / MISSING DECISIONS
Things a new coding agent would reasonably have to guess. Separate decisions that should be documented now from decisions that should remain deferred until the product needs them.

6. STRUCTURAL OR SECURITY RISKS
Only evidence-backed risks. Rank Critical / High / Medium / Low. Explain an actual failure mode, not just a best-practice slogan. Do not promote a low-confidence suspicion to a high-severity finding.

7. DOCUMENTATION OPPORTUNITIES
Suggest the smallest useful architecture/agent documentation additions. If the application already has strong docs, say so. Distinguish current global architecture guidance from one-off recipes and historical plans.

8. PRIORITIZED REMEDIATION
Three buckets:
- Do now: correctness/security or high-leverage ambiguity
- Do when touched: worthwhile normalization that does not justify churn today
- Leave alone: coherent differences, product-specific choices, intentional compatibility code, or speculative work

9. SUGGESTED AGENT ENTRYPOINT
Based on this repository as it exists today, draft a concise outline for what its AGENTS.md or equivalent should tell a fresh coding agent to read and preserve. If a good agent entrypoint already exists, recommend focused edits rather than pretending it is missing.

10. QUESTIONS FOR THE MAINTAINER
Only ask questions whose answers materially change the architectural diagnosis and cannot be determined from the repository. Maximum 5. If none are needed, say "None."

Before finalizing, challenge your own report:
- Did you mistake a preference for a defect?
- Did you recommend architecture the product does not need?
- Did you infer a pattern from one isolated example or search hit?
- Did you mistake legacy, migration, compatibility, provider-specific, or admin code for conflicting product precedent?
- Did you call a global lookup unsafe without considering whether its input is user-controlled, admin-only, webhook-authenticated, or internal job state?
- Did you treat an internal database ID as if it were a public identifier?
- Did you call a retrievable OAuth/provider token insecure merely because it is retrievable?
- Did you miss inherited authorization or base-controller protections?
- Did you call something "missing" that is actually deliberately deferred?
- Did you distinguish current documentation from historical plans?
- Did you provide file-level and call-site evidence for every important claim?

Then produce the report. Do not modify the application.