chore: add AGENTS.md files

AGENTS.md

@@ -0,0 +1,58 @@
+# Welcome to the Outline Monorepo!
+
+This document provides a guide for AI and human agents working with the Outline codebase.
+
+## Repository Structure
+
+The Outline monorepo is organized into three main components:
+
+*   `/client`: The Outline Client application, available on all major platforms. See [`client/AGENTS.md`](client/AGENTS.md).
+*   `/server_manager`: A graphical application to create and manage Outline Servers. See [`server_manager/AGENTS.md`](server_manager/AGENTS.md).
+*   `/infrastructure`: The build system and shared TypeScript utilities. See [`infrastructure/AGENTS.md`](infrastructure/AGENTS.md).
+
+## The `npm run action` Command
+
+The primary entry point for all development tasks is `npm run action <path>`, which resolves to `.action.sh` or `.action.mjs` files in the repo. Run `npm run action list` to see all available actions. Pass flags after `--`:
+
+```sh
+npm run action client/src/cordova/setup macos -- --buildMode=release
+```
+
+### Common Actions
+
+*   `npm run action list`: Lists all available actions.
+*   `npm run action client/web/start`: Starts a dev server for the shared web UI.
+*   `npm run action server_manager/www/start`: Starts a dev server for the Manager UI.
+*   `npm run action <component>/test`: Runs tests (e.g. `npm run action client/web/test`).
+*   `npm run action <component>/build`: Builds a component (e.g. `npm run action client/electron/build linux`).
+
+### Other useful commands
+
+*   `npm run reset`: Clean and reinstall all dependencies (fixes most build issues).
+*   `npm run storybook`: Launch the Storybook UI component explorer.
+*   `npm run lint:gts`: Lint TypeScript (pass filepaths on macOS; works on all files on Linux).
+
+## Code Style
+
+*   **TypeScript**: Follows [Google's TypeScript style](https://google.github.io/styleguide/tsguide.html), enforced by [`gts`](https://github.com/google/gts). Run `npm run lint:gts` to check and `npm run format:all` to auto-fix (Linux only for whole codebase; pass specific filepaths on macOS).
+*   **Go**: Follows standard Go style. Use `gofmt` and `go vet`.
+
+## Requirements
+
+| Component | Version |
+|-----------|---------|
+| Node.js   | 22 (lts/hydrogen) — run `nvm use` if you have nvm |
+| Go        | 1.22+   |
+
+Platform-specific requirements (Android SDK, Xcode, zig for cross-compilation) are documented in the relevant subdirectory AGENTS.md files.
+
+## Common Concepts
+
+*   **Access Keys**: Credentials used by Outline clients to connect to an Outline server. Generated by the Outline Manager.
+*   **Shadowbox**: The core proxy component of Outline, responsible for handling network traffic.
+*   **Outline Client**: The end-user application for connecting to the internet through an Outline server.
+*   **Server Manager**: The application used to create and manage Outline servers on cloud providers.
+*   **Electron**: Framework used to build the desktop versions of the Outline Client and Server Manager.
+*   **Cordova**: Framework used to build the mobile (iOS/Android) and macOS versions of the Outline Client.
+*   **Lit**: The UI framework for web components. All new components use Lit. The client has fully migrated; the server_manager still has legacy Polymer components in its app shell being migrated.
+*   **OutlineAction**: A custom build script (`.action.sh` or `.action.mjs`) that defines a task runnable via `npm run action`.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

README.md

@@ -14,6 +14,8 @@ Outline makes it easy for anyone to create a VPN server, allowing you to share a
 
 Interested in **contributing to Outline?** See our [Contributing Guide](CONTRIBUTING.md) for more information.
 
+See [AGENTS.md](./AGENTS.md) for AI agent and developer guidance.
+
 You can also **join the Outline Community** by signing up for the [IFF Mattermost](https://wiki.digitalrights.community/index.php?title=IFF_Mattermost)!
 
 For customer support and to **contact us directly**, go to https://support.getoutline.org.

client/AGENTS.md

@@ -0,0 +1,71 @@
+# <img alt="Outline Client Logo" src="../docs/resources/logo_client.png" title="Outline Client" width="32">&nbsp;&nbsp;Outline Client
+
+This document provides a guide for AI and human agents working on the Outline Client.
+
+## Directory Structure
+
+The `/client` directory contains the source code for all Outline client applications. Here's a breakdown of the key subdirectories:
+
+*   `/electron`: Contains the Electron-specific code for the desktop client, including the main process, preload scripts, and build configurations.
+*   `/go`: Contains shared Go source code that is used across platforms for networking and other functionality that cannot be done on the browser.
+*   `/src/cordova`: Contains the Cordova-specific code for the mobile (iOS and Android) and macOS (via Mac Catalyst) clients.
+*   `/src/www`: Contains the shared web-based UI components, built with TypeScript. This code is used by both the Electron and Cordova applications.
+
+## Key Technologies
+
+*   **Electron**: Used to build the desktop client for Windows and Linux.
+*   **Cordova**: Used to build the clients for macOS, iOS, Android.
+*   **[Lit](https://lit.dev/)**: The UI framework for all web components in the client.
+*   **TypeScript**: Used for all web-based code.
+*   **Go**: Used to implement the networking and other shared code.
+
+## Building and Running the Client
+
+The `npm run action` command is used to build and run the client applications.
+
+### Shared Web App Development
+
+If you are making changes to the shared web app and do not need to test platform-specific functionality, you can test in a desktop browser by running:
+
+```sh
+npm run action client/web/start
+```
+
+The app logic is located in `src/www/app`. UI components are located in `src/www/ui_components`. To work on an individual UI element, use Storybook:
+
+```sh
+npm run storybook
+```
+
+### Electron Client
+
+*   **Build (Linux)**: `npm run action client/electron/build linux`
+*   **Build (Windows)**: `npm run action client/electron/build windows`
+
+### Cordova Clients
+
+*   **Build (Android)**: `npm run action client/src/cordova/build android`
+*   **Build (iOS)**: `npm run action client/src/cordova/build ios`
+*   **Build (macOS)**: `npm run action client/src/cordova/build macos`
+
+### Configuration Flags
+
+Certain actions take configuration flags. Since they are run through `npm`, you must use the `--` separator to pass them to the underlying process. For example:
+
+```sh
+SENTRY_DSN=<your sentry dsn> npm run action client/src/cordova/setup macos -- --buildMode=release --versionName=<your version name>
+```
+
+## Testing the Client
+
+*   **Web Components**: `npm run action client/web/test`
+*   **Go Backend**: `go test -race -bench=. -benchtime=100ms ./client/...`
+*   **OutlineAppleLib (macOS)**: `npm run action client/src/cordova/test macos`
+*   **OutlineAppleLib (iOS)**: `npm run action client/src/cordova/test ios`
+
+## Additional Resources
+
+*   [Life of a Packet](/docs/life_of_a_packet.md): Learn how the Outline Client works.
+*   [Developing for Apple (macOS and iOS)](src/cordova/apple)
+*   [Developing for Android](src/cordova/android)
+*   [Developing for Electron (Windows and Linux)](electron)

infrastructure/AGENTS.md

@@ -0,0 +1,39 @@
+# Outline Infrastructure
+
+This document provides a guide for AI agents working with the Outline infrastructure.
+
+## Directory Structure
+
+The `/infrastructure` directory contains the build system, deployment scripts, and other application-independent code for the Outline project.
+
+*   `/build`: Contains the core scripts for the `npm run action` command.
+*   `*.ts`: Various TypeScript files providing utility functions for the build system and applications, similar to third-party dependencies.
+
+## The `npm run action` Build System
+
+The `npm run action` command is the heart of the Outline build system. It is implemented as a set of Node.js scripts in the `/infrastructure/build` directory. The main entry point is `run_action.mjs`, which parses the command-line arguments and executes the corresponding action script.
+
+### Creating a New Action
+
+To create a new action, you need to create a new `.mjs` file in the appropriate directory (e.g., `server_manager/www/my_action.mjs`). This file should export a default function that will be executed when the action is run.
+
+The function will be passed an `options` object containing the command-line arguments. You can use the utility functions in `/infrastructure` to perform common tasks like spawning processes, downloading files, and creating reload servers.
+
+### Example Action
+
+```javascript
+// server_manager/www/my_action.mjs
+import { spawnStream } from '../../infrastructure/build/spawn_stream.mjs';
+
+export default async function(options) {
+  await spawnStream('echo', ['Hello, World!']);
+}
+```
+
+This action can be run with the command `npm run action server_manager/www/my_action`.
+
+## Testing the Infrastructure
+
+The infrastructure code can be tested by running the following command:
+
+`npm run action infrastructure/test`

server_manager/AGENTS.md

@@ -0,0 +1,72 @@
+# Outline Server Manager
+
+This document provides a guide for AI and human agents working on the Outline Server Manager.
+
+## Directory Structure
+
+The `/server_manager` directory contains the source code for the Outline Server Manager, which is available as a web-based application and an Electron desktop application.
+
+*   `/www`: Contains the web application that serves as the main UI for the Server Manager.
+*   `/electron`: Houses the Electron-specific code for the desktop version of the Server Manager.
+*   `/cloud`: Includes the APIs for interacting with cloud providers like DigitalOcean and Google Cloud Platform.
+*   `/install_scripts`: Contains the shell scripts used to install and configure Outline servers on various cloud providers.
+
+## Key Technologies
+
+*   **Lit**: The primary UI framework for the Server Manager's web-based components. New components use Lit.
+*   **Polymer**: Still used in legacy app shell components (`/www/ui_components/`). Being migrated to Lit.
+*   **Electron**: Used to build the desktop version of the Server Manager.
+*   **TypeScript**: Used for all web-based code.
+*   **Shadowbox**: The core proxy component of Outline, which is managed by the Server Manager.
+
+## Prerequisites
+
+Ensure you have installed Node.js and have run `npm ci` in the root directory.
+
+## Building and Running the Server Manager
+
+The `npm run action` command is used to build and run the Server Manager.
+
+### Web Application
+
+*   **Build**: `npm run action server_manager/www/build`
+*   **Run for development**: `npm run action server_manager/www/start`
+
+### Electron Application
+
+*   **Build**: `npm run action server_manager/electron/build ${PLATFORM}`
+*   **Run**: `npm run action server_manager/electron/start ${PLATFORM}`
+*   **Run with development build**: `BUILD_ENV=development npm run action server_manager/electron/start ${PLATFORM}`
+
+Where `${PLATFORM}` is one of `linux`, `macos`, `windows`. If omitted, it assumes the host platform.
+
+### Packaging
+
+To build the app binary:
+
+```
+npm run action server_manager/electron/package ${PLATFORM} -- --buildMode=[debug,release]
+```
+
+The per-platform standalone apps will be at `output/build/server_manager/electron/static/dist`:
+
+- **Windows**: `.exe` — only generated if [wine](https://www.winehq.org/download) is installed.
+- **Linux**: `.AppImage`
+- **macOS**: `.dmg` and `.zip` (both required for auto-update). You may need to run `security unlock-keychain login.keychain` so electron-builder has access to your certificates.
+
+## Debugging
+
+You can run an existing binary in debug mode by setting `OUTLINE_DEBUG=true`. This will enable the Developer menu on the application window.
+
+## Error Reporting
+
+To enable error reporting through [Sentry](https://sentry.io/) for local builds, run:
+
+```bash
+export SENTRY_DSN=[Sentry DSN URL]
+npm run action server_manager/electron/start ${PLATFORM}
+```
+
+## Testing the Server Manager
+
+*   **Web Application**: `npm run action server_manager/test`

server_manager/README.md

@@ -49,6 +49,12 @@ The per-platform standalone apps will be at `output/build/server_manager/electro
 
 > NOTE: If you are building for macOS, you may need to run `security unlock-keychain login.keychain` so electron-builder has access to your certificates.
 
+## Testing
+
+```
+npm run action server_manager/test
+```
+
 ## Error reporting
 
 To enable error reporting through [Sentry](https://sentry.io/) for local builds, run: