Improve Amp orb development workflow

[skyfallwastaken]

Summary of the problem

Fresh Amp orbs had slow first loads and fragile portal restarts. Development sign-in links could also use the internal proxy host. Agents lacked clear guidance on system ownership and safe architectural changes.

Describe your changes

Added reliable orb setup and resume hooks, a dedicated portal service, prebuilt client assets and canonical development sign-in links. Added engineering guidance and an architecture map for safer Rails changes.

Screenshots / Media

No user-facing visual changes.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[greptile-apps]

Greptile Summary

The PR improves Amp orb setup and resume behavior, adds a dedicated Rails portal service, generates canonical development magic links, and documents architectural guidance.

• Adds setup and resume hooks for Docker, databases, Vite assets, and Amp services.
• Adds a Compose portal profile and Amp service definition.
• Adds development-only login and logout endpoints.
• Uses PUBLIC_URL when constructing development magic links.
• Expands contributor and architecture documentation.

Confidence Score: 3/5

The arbitrary-email login exposed through the published development portal must be access-controlled before this PR is safe to merge.

A caller who obtains the portal URL can request the new development login route for any known local email and receive that user's authenticated session without proving control of the identity.

Files Needing Attention: app/controllers/dev_controller.rb, config/routes.rb, docker-compose.yml

Security Review

The development portal exposes a direct arbitrary-email session-login endpoint while running Rails in development mode on a published port. How this was verified: The published portal loads the development route, which resolves the caller-supplied email and writes its user ID directly into the session without an authentication token or authorization check.

Important Files Changed

Filename	Overview
app/controllers/dev_controller.rb	Adds direct development login/logout actions, but the login is reachable through the published development portal without caller authentication and lacks tests.
config/routes.rb	Adds development-only routes, including a state-changing GET login route exposed whenever Rails runs in development mode.
docker-compose.yml	Adds a dedicated development portal profile on host port 3001 and database health checking; the published port makes the development authentication route security-sensitive.
app/controllers/sessions_controller.rb	Constructs non-production magic links from PUBLIC_URL with a request-origin fallback, with focused coverage for supported configurations.
test/controllers/sessions_controller_test.rb	Covers canonical and fallback magic-link origins but omits the newly added DevController behavior.
.agents/setup	Automates Docker installation/startup, asset compilation, database preparation, and portal startup for fresh orbs.
.agents/resume	Restarts Docker when needed, restores Compose services, and ensures the Amp portal service is running.
.amp/services.yaml	Defines the managed portal command and forwards the public portal URL.
AGENTS.md	Adds detailed ownership, correctness, portal workflow, authentication, and pull-request guidance.
docs/architecture.md	Adds an architecture map covering application boundaries, sources of truth, authentication, jobs, and persistence invariants.

Sequence Diagram

sequenceDiagram
  participant Caller
  participant Portal as Amp Portal :3001
  participant Dev as DevController
  participant DB as EmailAddress
  Caller->>Portal: "GET /__dev/log-me-in/user@example.com"
  Portal->>Dev: Development route
  Dev->>DB: Find email address
  DB-->>Dev: user_id
  Dev->>Dev: reset_session and set session[:user_id]
  Dev-->>Caller: Authenticated cookie and redirect

Loading

Prompt To Fix All With AI

### Issue 1
app/controllers/dev_controller.rb:13-17
**Arbitrary-email portal authentication**

When a caller reaches the Amp portal, this action accepts any known local email and writes its user ID directly into the session without a token or authorization check, allowing the caller to obtain that user's authenticated session, including an administrator's. **How this was verified:** The published portal runs Rails in development mode, loads this route and assigns the caller-selected email's user ID directly to `session[:user_id]`.

### Issue 2
app/controllers/dev_controller.rb:1-31
**Development endpoints lack tests**

The new controller and routes have no tests covering development-environment isolation, successful and unknown-email login behavior, session reset or logout. This leaves regressions in the new authentication workflow undetected and violates the repository requirement that new functionality include tests.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "Improve orb development safety and perfo..." | Re-trigger Greptile}