diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
new file mode 100644
index 0000000..196277e
--- /dev/null
+++ b/.github/workflows/test.yml
@@ -0,0 +1,32 @@
+name: tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  phpunit:
+    name: PHPUnit (PHP ${{ matrix.php }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.2', '8.3', '8.4']
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: pdo, pdo_sqlite, sqlite3, curl, simplexml
+          coverage: none
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: composer install --no-interaction --no-progress --prefer-dist
+
+      - name: Run PHPUnit
+        run: vendor/bin/phpunit
diff --git a/.gitignore b/.gitignore
index afc0e2b..740022d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,11 @@
 /.php-cs-fixer.cache
 
 /composer.lock
+/composer.phar
 /vendor/
 
+/.phpunit.cache/
+/tests/tmp/
+
 /yarn.lock
 /node_modules/
diff --git a/composer.json b/composer.json
index bdb1425..98df486 100644
--- a/composer.json
+++ b/composer.json
@@ -1,5 +1,9 @@
 {
     "require-dev": {
-        "friendsofphp/php-cs-fixer": "^3.48"
+        "friendsofphp/php-cs-fixer": "^3.48",
+        "phpunit/phpunit": "^11.0"
+    },
+    "scripts": {
+        "test": "phpunit"
     }
 }
diff --git a/phpunit.xml.dist b/phpunit.xml.dist
new file mode 100644
index 0000000..632c115
--- /dev/null
+++ b/phpunit.xml.dist
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="tests/bootstrap.php"
+         cacheDirectory=".phpunit.cache"
+         colors="true"
+         failOnWarning="true"
+         failOnRisky="true"
+         beStrictAboutOutputDuringTests="true">
+    <testsuites>
+        <testsuite name="Unit">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>
diff --git a/tests/CurlRequestTest.php b/tests/CurlRequestTest.php
new file mode 100644
index 0000000..180df2d
--- /dev/null
+++ b/tests/CurlRequestTest.php
@@ -0,0 +1,30 @@
+<?php
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * CurlRequest is the per-request token carrier. The fact that the token is
+ * a constructor argument (not global state) is the load-bearing property
+ * that lets multi-account work avoid touching the network layer — pin it.
+ */
+final class CurlRequestTest extends TestCase
+{
+    public function testConstructorAssignsAllFields(): void
+    {
+        $callback = static function () {};
+        $request = new CurlRequest('https://api.github.com/user', 'etag-1', 'tok', $callback);
+
+        $this->assertSame('https://api.github.com/user', $request->url);
+        $this->assertSame('etag-1', $request->etag);
+        $this->assertSame('tok', $request->token);
+        $this->assertSame($callback, $request->callback);
+    }
+
+    public function testTokenMayBeNullForUnauthenticatedRequests(): void
+    {
+        $request = new CurlRequest('https://api.github.com/', null, null, static function () {});
+
+        $this->assertNull($request->token);
+        $this->assertNull($request->etag);
+    }
+}
diff --git a/tests/ItemRenderTest.php b/tests/ItemRenderTest.php
new file mode 100644
index 0000000..b9813dd
--- /dev/null
+++ b/tests/ItemRenderTest.php
@@ -0,0 +1,125 @@
+<?php
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Characterization tests for Item::toXml. The XML structure, attribute
+ * ordering, escaping, and the baseUrl-prefix/enterprise-prefix rules are
+ * exercised against fixed inputs so that any accidental drift shows up as
+ * a diff in CI.
+ */
+final class ItemRenderTest extends TestCase
+{
+    public function testMinimalItemProducesExpectedXml(): void
+    {
+        $item = Item::create()->title('repo');
+        $xml = Item::toXml([$item], false, false, 'https://github.com');
+
+        $expectedUid = md5('repo');
+        $expected = '<?xml version="1.0"?>'."\n".
+            '<items><item uid="'.$expectedUid.'" autocomplete=" repo"><icon>icon.png</icon><title>repo</title></item></items>'."\n";
+
+        $this->assertSame($expected, $xml);
+    }
+
+    public function testAbsolutePathArgIsPrefixedWithBaseUrl(): void
+    {
+        $item = Item::create()->title('repo')->arg('/owner/repo');
+        $xml = Item::toXml([$item], false, false, 'https://github.com');
+
+        $this->assertStringContainsString('arg="https://github.com/owner/repo"', $xml);
+    }
+
+    public function testEnterpriseFlagPrefixesNonUrlArg(): void
+    {
+        $item = Item::create()->title('search')->arg('foo bar');
+        $xml = Item::toXml([$item], true, false, 'https://ghe.example.com');
+
+        $this->assertStringContainsString('arg="e foo bar"', $xml);
+    }
+
+    public function testNonEnterpriseDoesNotPrefixArg(): void
+    {
+        $item = Item::create()->title('search')->arg('foo bar');
+        $xml = Item::toXml([$item], false, false, 'https://github.com');
+
+        $this->assertStringContainsString('arg="foo bar"', $xml);
+    }
+
+    public function testAbsoluteUrlArgIsUsedVerbatim(): void
+    {
+        $item = Item::create()->title('site')->arg('https://example.com/thing');
+        $xml = Item::toXml([$item], false, false, 'https://github.com');
+
+        $this->assertStringContainsString('arg="https://example.com/thing"', $xml);
+    }
+
+    public function testInvalidItemAppendsEllipsisAndValidNo(): void
+    {
+        $item = Item::create()->title('partial')->valid(false);
+        $xml = Item::toXml([$item], false, false, 'https://github.com');
+
+        $this->assertStringContainsString('valid="no"', $xml);
+        $this->assertStringContainsString('<title>partial&#x2026;</title>', $xml);
+    }
+
+    public function testInvalidItemUsesCustomSuffix(): void
+    {
+        $item = Item::create()->title('type')->valid(false, ' more');
+        $xml = Item::toXml([$item], false, false, 'https://github.com');
+
+        $this->assertStringContainsString('<title>type more</title>', $xml);
+    }
+
+    public function testSubtitleAndTitleAreHtmlEscaped(): void
+    {
+        $item = Item::create()->title('<b>bold</b>')->subtitle('a & b');
+        $xml = Item::toXml([$item], false, false, 'https://github.com');
+
+        $this->assertStringContainsString('<title>&lt;b&gt;bold&lt;/b&gt;</title>', $xml);
+        $this->assertStringContainsString('<subtitle>a &amp; b</subtitle>', $xml);
+    }
+
+    public function testHotkeyFlagStripsLeadingAutocompleteSpace(): void
+    {
+        $item = Item::create()->title('repo');
+        $xml = Item::toXml([$item], false, true, 'https://github.com');
+
+        $this->assertStringContainsString('autocomplete="repo"', $xml);
+    }
+
+    public function testPrefixIsIncludedInDisplayTitleButNotAutocompleteByDefault(): void
+    {
+        $item = Item::create()->prefix('gh ')->title('repo');
+        $xml = Item::toXml([$item], false, false, 'https://github.com');
+
+        $this->assertStringContainsString('<title>gh repo</title>', $xml);
+        $this->assertStringContainsString('autocomplete=" repo"', $xml);
+    }
+
+    public function testPrefixIncludedInAutocompleteWhenNotOnlyTitle(): void
+    {
+        $item = Item::create()->prefix('gh ', false)->title('repo');
+        $xml = Item::toXml([$item], false, false, 'https://github.com');
+
+        $this->assertStringContainsString('autocomplete=" gh repo"', $xml);
+    }
+
+    public function testMultipleItemsAreEmittedInOrder(): void
+    {
+        $items = [
+            Item::create()->title('first'),
+            Item::create()->title('second'),
+            Item::create()->title('third'),
+        ];
+        $xml = Item::toXml($items, false, false, 'https://github.com');
+
+        $firstPos = strpos($xml, '<title>first</title>');
+        $secondPos = strpos($xml, '<title>second</title>');
+        $thirdPos = strpos($xml, '<title>third</title>');
+
+        $this->assertNotFalse($firstPos);
+        $this->assertLessThan($secondPos, $firstPos);
+        $this->assertLessThan($thirdPos, $secondPos);
+    }
+}
diff --git a/tests/WorkflowConfigTest.php b/tests/WorkflowConfigTest.php
new file mode 100644
index 0000000..0a439da
--- /dev/null
+++ b/tests/WorkflowConfigTest.php
@@ -0,0 +1,43 @@
+<?php
+
+require_once __DIR__.'/WorkflowTestCase.php';
+
+final class WorkflowConfigTest extends WorkflowTestCase
+{
+    public function testSetAndGetConfigRoundTrip(): void
+    {
+        Workflow::init();
+
+        Workflow::setConfig('greeting', 'hello');
+
+        $this->assertSame('hello', Workflow::getConfig('greeting'));
+    }
+
+    public function testGetConfigReturnsDefaultWhenMissing(): void
+    {
+        Workflow::init();
+
+        $this->assertNull(Workflow::getConfig('missing'));
+        $this->assertSame('fallback', Workflow::getConfig('missing', 'fallback'));
+    }
+
+    public function testSetConfigOverwritesExistingValue(): void
+    {
+        Workflow::init();
+
+        Workflow::setConfig('k', 'v1');
+        Workflow::setConfig('k', 'v2');
+
+        $this->assertSame('v2', Workflow::getConfig('k'));
+    }
+
+    public function testRemoveConfigDeletesKey(): void
+    {
+        Workflow::init();
+
+        Workflow::setConfig('k', 'v');
+        Workflow::removeConfig('k');
+
+        $this->assertNull(Workflow::getConfig('k'));
+    }
+}
diff --git a/tests/WorkflowEnterpriseUrlTest.php b/tests/WorkflowEnterpriseUrlTest.php
new file mode 100644
index 0000000..cf37632
--- /dev/null
+++ b/tests/WorkflowEnterpriseUrlTest.php
@@ -0,0 +1,58 @@
+<?php
+
+require_once __DIR__.'/WorkflowTestCase.php';
+
+/**
+ * Pins the URL derivation performed by Workflow::init when the enterprise
+ * flag is set: baseUrl is read from the enterprise_url config key, and the
+ * API/gist URLs are derived from it. When no config value is present the
+ * derived URLs become null — this is the current (pre-multi-account) shape
+ * and callers depend on it.
+ */
+final class WorkflowEnterpriseUrlTest extends WorkflowTestCase
+{
+    public function testDefaultGithubUrls(): void
+    {
+        Workflow::init();
+
+        $this->assertSame('https://github.com', Workflow::getBaseUrl());
+        $this->assertSame('https://api.github.com', Workflow::getApiUrl());
+        $this->assertSame('https://gist.github.com', Workflow::getGistUrl());
+    }
+
+    public function testEnterpriseUrlsDerivedFromConfig(): void
+    {
+        Workflow::init();
+        Workflow::setConfig('enterprise_url', 'https://ghe.example.com');
+
+        agw_test_reset_workflow();
+        Workflow::init(true);
+
+        $this->assertSame('https://ghe.example.com', Workflow::getBaseUrl());
+        $this->assertSame('https://ghe.example.com/api/v3', Workflow::getApiUrl());
+        $this->assertSame('https://ghe.example.com/gist', Workflow::getGistUrl());
+    }
+
+    public function testEnterpriseUrlsAreNullWhenConfigMissing(): void
+    {
+        Workflow::init(true);
+
+        $this->assertNull(Workflow::getBaseUrl());
+        $this->assertNull(Workflow::getApiUrl());
+        $this->assertNull(Workflow::getGistUrl());
+    }
+
+    public function testGetApiUrlAppendsPathAndPerPage(): void
+    {
+        Workflow::init();
+
+        $this->assertSame(
+            'https://api.github.com/user/repos?per_page=100',
+            Workflow::getApiUrl('/user/repos')
+        );
+        $this->assertSame(
+            'https://api.github.com/search/repositories?q=foo&per_page=100',
+            Workflow::getApiUrl('/search/repositories?q=foo')
+        );
+    }
+}
diff --git a/tests/WorkflowSchemaTest.php b/tests/WorkflowSchemaTest.php
new file mode 100644
index 0000000..ce274b5
--- /dev/null
+++ b/tests/WorkflowSchemaTest.php
@@ -0,0 +1,95 @@
+<?php
+
+require_once __DIR__.'/WorkflowTestCase.php';
+
+/**
+ * Pins the SQLite schema that Workflow::init creates on a fresh database,
+ * plus the fact that init is safe to call against an existing database
+ * without recreating tables. Multi-account work will alter request_cache;
+ * these assertions are the canary for that migration.
+ */
+final class WorkflowSchemaTest extends WorkflowTestCase
+{
+    public function testInitCreatesConfigTableWithExpectedColumns(): void
+    {
+        Workflow::init();
+
+        $columns = $this->tableColumns('config');
+
+        $this->assertSame(['key', 'value'], array_column($columns, 'name'));
+        $this->assertSame(1, $this->columnByName($columns, 'key')['pk']);
+        $this->assertSame(1, $this->columnByName($columns, 'key')['notnull']);
+    }
+
+    public function testInitCreatesRequestCacheTableWithExpectedColumns(): void
+    {
+        Workflow::init();
+
+        $columns = $this->tableColumns('request_cache');
+
+        $this->assertSame(
+            ['url', 'timestamp', 'etag', 'content', 'refresh', 'parent'],
+            array_column($columns, 'name')
+        );
+        $this->assertSame(1, $this->columnByName($columns, 'url')['pk']);
+    }
+
+    public function testInitCreatesParentUrlIndex(): void
+    {
+        Workflow::init();
+
+        $pdo = $this->db();
+        $row = $pdo->query("SELECT sql FROM sqlite_master WHERE type = 'index' AND name = 'parent_url'")->fetch(PDO::FETCH_ASSOC);
+
+        $this->assertIsArray($row);
+        $this->assertStringContainsString('request_cache', $row['sql']);
+        $this->assertStringContainsString('parent', $row['sql']);
+    }
+
+    public function testInitIsIdempotentAcrossReopen(): void
+    {
+        Workflow::init();
+        Workflow::setConfig('persisted', 'yes');
+
+        agw_test_reset_workflow();
+        Workflow::init();
+
+        $this->assertSame('yes', Workflow::getConfig('persisted'));
+
+        $columns = $this->tableColumns('config');
+        $this->assertSame(['key', 'value'], array_column($columns, 'name'));
+    }
+
+    private function db(): PDO
+    {
+        return new PDO('sqlite:'.$this->dataDir.'/db.sqlite');
+    }
+
+    /** @return array<int,array{name:string,pk:int,notnull:int}> */
+    private function tableColumns(string $table): array
+    {
+        $stmt = $this->db()->query('PRAGMA table_info('.$table.')');
+        $columns = [];
+        foreach ($stmt->fetchAll(PDO::FETCH_ASSOC) as $row) {
+            $columns[] = [
+                'name' => $row['name'],
+                'pk' => (int) $row['pk'],
+                'notnull' => (int) $row['notnull'],
+            ];
+        }
+
+        return $columns;
+    }
+
+    /** @param array<int,array{name:string,pk:int,notnull:int}> $columns */
+    private function columnByName(array $columns, string $name): array
+    {
+        foreach ($columns as $column) {
+            if ($column['name'] === $name) {
+                return $column;
+            }
+        }
+
+        $this->fail('Column '.$name.' not found');
+    }
+}
diff --git a/tests/WorkflowTestCase.php b/tests/WorkflowTestCase.php
new file mode 100644
index 0000000..5b3f76e
--- /dev/null
+++ b/tests/WorkflowTestCase.php
@@ -0,0 +1,29 @@
+<?php
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Base test case that gives each test a fresh Workflow data directory and
+ * resets the static Workflow state. Workflow is a static class, so without
+ * this its SQLite handle and cached prepared statements would leak between
+ * tests.
+ */
+abstract class WorkflowTestCase extends TestCase
+{
+    /** @var string */
+    protected $dataDir;
+
+    protected function setUp(): void
+    {
+        $this->dataDir = agw_test_tmp_dir();
+        putenv('alfred_workflow_data='.$this->dataDir);
+        agw_test_reset_workflow();
+    }
+
+    protected function tearDown(): void
+    {
+        agw_test_reset_workflow();
+        putenv('alfred_workflow_data');
+        agw_test_rmrf($this->dataDir);
+    }
+}
diff --git a/tests/WorkflowTokenTest.php b/tests/WorkflowTokenTest.php
new file mode 100644
index 0000000..a594c9b
--- /dev/null
+++ b/tests/WorkflowTokenTest.php
@@ -0,0 +1,67 @@
+<?php
+
+require_once __DIR__.'/WorkflowTestCase.php';
+
+/**
+ * Pins the dual-slot token behavior: the github.com token and the enterprise
+ * token live in two separate config keys and MUST NOT collide. Multi-account
+ * work (PR #2) will change the storage model; these tests ensure the
+ * migration preserves the current isolation guarantees.
+ */
+final class WorkflowTokenTest extends WorkflowTestCase
+{
+    public function testGithubTokenStoredUnderAccessTokenKey(): void
+    {
+        Workflow::init();
+
+        Workflow::setAccessToken('gh-token');
+
+        $this->assertSame('gh-token', Workflow::getAccessToken());
+        $this->assertSame('gh-token', Workflow::getConfig('access_token'));
+        $this->assertNull(Workflow::getConfig('enterprise_access_token'));
+    }
+
+    public function testEnterpriseTokenStoredUnderEnterpriseKey(): void
+    {
+        Workflow::init(true);
+
+        Workflow::setAccessToken('ghe-token');
+
+        $this->assertSame('ghe-token', Workflow::getAccessToken());
+        $this->assertSame('ghe-token', Workflow::getConfig('enterprise_access_token'));
+        $this->assertNull(Workflow::getConfig('access_token'));
+    }
+
+    public function testGithubAndEnterpriseTokensDoNotCollide(): void
+    {
+        Workflow::init();
+        Workflow::setAccessToken('gh-token');
+
+        agw_test_reset_workflow();
+        Workflow::init(true);
+        Workflow::setAccessToken('ghe-token');
+
+        $this->assertSame('ghe-token', Workflow::getAccessToken());
+
+        agw_test_reset_workflow();
+        Workflow::init();
+        $this->assertSame('gh-token', Workflow::getAccessToken());
+    }
+
+    public function testRemoveAccessTokenOnlyAffectsActiveSlot(): void
+    {
+        Workflow::init();
+        Workflow::setAccessToken('gh-token');
+
+        agw_test_reset_workflow();
+        Workflow::init(true);
+        Workflow::setAccessToken('ghe-token');
+        Workflow::removeAccessToken();
+
+        $this->assertNull(Workflow::getAccessToken());
+
+        agw_test_reset_workflow();
+        Workflow::init();
+        $this->assertSame('gh-token', Workflow::getAccessToken());
+    }
+}
diff --git a/tests/bootstrap.php b/tests/bootstrap.php
new file mode 100644
index 0000000..2ffd930
--- /dev/null
+++ b/tests/bootstrap.php
@@ -0,0 +1,72 @@
+<?php
+
+// workflow.php uses relative requires for item.php and curl.php, so the
+// include path must point at the repo root when it is loaded.
+chdir(__DIR__.'/..');
+require __DIR__.'/../workflow.php';
+
+/**
+ * Create a fresh temp directory that will be used as alfred_workflow_data.
+ * Each test gets its own directory to prevent SQLite file collisions and
+ * to keep tests independent of one another.
+ */
+function agw_test_tmp_dir(): string
+{
+    $dir = sys_get_temp_dir().'/agw-test-'.bin2hex(random_bytes(8));
+    mkdir($dir, 0755, true);
+
+    return $dir;
+}
+
+/**
+ * Recursively remove a test directory.
+ */
+function agw_test_rmrf(string $dir): void
+{
+    if (!is_dir($dir)) {
+        return;
+    }
+    foreach (scandir($dir) as $entry) {
+        if ('.' === $entry || '..' === $entry) {
+            continue;
+        }
+        $path = $dir.'/'.$entry;
+        if (is_dir($path)) {
+            agw_test_rmrf($path);
+        } else {
+            unlink($path);
+        }
+    }
+    rmdir($dir);
+}
+
+/**
+ * Reset the static state of the Workflow class between tests. Because
+ * Workflow is a singleton-style static class, state leaks between tests
+ * otherwise — fresh SQLite handles, urls, and item buffers are required.
+ */
+function agw_test_reset_workflow(): void
+{
+    $ref = new ReflectionClass(Workflow::class);
+    $resets = [
+        'filePids' => null,
+        'fileDb' => null,
+        'db' => null,
+        'statements' => [],
+        'enterprise' => null,
+        'baseUrl' => 'https://github.com',
+        'apiUrl' => 'https://api.github.com',
+        'gistUrl' => 'https://gist.github.com',
+        'query' => null,
+        'hotkey' => null,
+        'items' => [],
+        'refreshUrls' => [],
+        'debug' => false,
+    ];
+    foreach ($resets as $name => $value) {
+        if ($ref->hasProperty($name)) {
+            $prop = $ref->getProperty($name);
+            $prop->setValue(null, $value);
+        }
+    }
+}