docs: add GitHub App manifest files

.github/workflows/drift-detection.yml

@@ -2,10 +2,6 @@ name: Repository Drift Detection
 
 on:
   pull_request:
-    paths:
-      - 'REPOSITORIES.md'
-      - 'scripts/**'
-      - '.github/workflows/drift-detection.yml'
 
 jobs:
   detect-drift:

REPOSITORIES.md

@@ -116,8 +116,3 @@ Track implementation progress in GitHub issue #9.
 ## webapp
 - Description: Web application interface for worlddriven
 - Topics: webapp, web, frontend, worlddriven
-
-## test
-- Description: Test repository for migration automation
-- Topics: test, migration, automation
-- Origin: TooAngel/worlddriven-migration-test

github-apps/README.md

@@ -0,0 +1,84 @@
+# WorldDriven GitHub Apps
+
+This directory contains the manifest files for WorldDriven's GitHub Apps. These manifests define the permissions, events, and configuration for each app.
+
+## Apps Overview
+
+| App | Purpose | Permissions |
+|-----|---------|-------------|
+| [worlddriven](worlddriven.json) | PR voting and auto-merge | checks, contents, issues, pull_requests, statuses, workflows |
+| [worlddriven-migrate](worlddriven-migrate.json) | One-time repository transfer | administration, metadata |
+
+## WorldDriven (Main App)
+
+The main app handles the democratic PR management system:
+- Monitors pull requests and reviews
+- Calculates voting weights based on contributions
+- Automatically merges PRs when voting threshold is reached
+- Posts status updates and comments
+
+**Install**: [github.com/apps/worlddriven](https://github.com/apps/worlddriven)
+
+## WorldDriven Migrate
+
+A minimal app for transferring repositories to the worlddriven org:
+- Only used during repository migration
+- Requires Administration permission to perform transfers
+- Can be uninstalled after migration completes
+
+**Install**: [github.com/apps/worlddriven-migrate](https://github.com/apps/worlddriven-migrate)
+
+## Why Two Apps?
+
+We use separate apps to follow the principle of least privilege:
+
+1. **Trust**: Users are more likely to install an app with minimal permissions
+2. **Security**: The main app doesn't need admin access for normal operations
+3. **Clarity**: Each app has a clear, single purpose
+4. **Transparency**: Users know exactly why each permission is needed
+
+## Using Manifests
+
+These manifests can be used with GitHub's [App Manifest Flow](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest) to create or recreate the apps.
+
+### Creating an App from Manifest
+
+1. Navigate to GitHub organization settings
+2. Go to Developer settings > GitHub Apps > New GitHub App
+3. Or use the manifest flow programmatically:
+
+```html
+<form action="https://github.com/organizations/worlddriven/settings/apps/new" method="post">
+  <input type="hidden" name="manifest" value='<JSON_MANIFEST_HERE>'>
+  <button type="submit">Create GitHub App</button>
+</form>
+```
+
+### Manifest Parameters
+
+| Field | Description |
+|-------|-------------|
+| `name` | Display name of the app |
+| `url` | Homepage URL |
+| `hook_attributes.url` | Webhook endpoint URL |
+| `description` | App description shown to users |
+| `public` | Whether app can be installed by anyone |
+| `default_events` | GitHub events the app subscribes to |
+| `default_permissions` | Permissions requested by the app |
+
+## Updating Apps
+
+GitHub Apps cannot be updated via API. To change permissions or settings:
+
+1. Go to [github.com/organizations/worlddriven/settings/apps](https://github.com/organizations/worlddriven/settings/apps)
+2. Select the app to modify
+3. Update settings manually
+4. Update the manifest file in this repository to keep documentation in sync
+
+**Note**: When permissions are added, existing installations must approve the new permissions.
+
+## References
+
+- [GitHub App Manifest Flow](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest)
+- [Permissions for GitHub Apps](https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps)
+- [Choosing Permissions](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app)

github-apps/worlddriven-migrate.json

@@ -0,0 +1,16 @@
+{
+  "name": "WorldDriven Migrate",
+  "url": "https://www.worlddriven.org/migrate",
+  "hook_attributes": {
+    "url": "https://www.worlddriven.org/api/webhooks/migrate"
+  },
+  "description": "One-time repository migration to the worlddriven organization.\n\nThis app enables automated transfer of your repository to the worlddriven org after your migration PR has been approved by the community.\n\nHow It Works:\n1. Create a PR adding your repository to REPOSITORIES.md\n2. Wait for community approval through worlddriven voting\n3. Install this app on your repository\n4. Your repository is automatically transferred to the worlddriven org\n5. The PR auto-merges once the transfer completes\n\nThis app only requires Administration permission to perform the one-time transfer. You can uninstall it after migration is complete.\n\nNote: This is a separate app from the main WorldDriven app to keep permissions minimal. The main app handles PR voting and auto-merge; this app only handles repository transfers.",
+  "public": true,
+  "default_events": [
+    "installation_repositories"
+  ],
+  "default_permissions": {
+    "administration": "write",
+    "metadata": "read"
+  }
+}

github-apps/worlddriven.json

@@ -0,0 +1,28 @@
+{
+  "name": "WorldDriven",
+  "url": "https://www.worlddriven.org",
+  "hook_attributes": {
+    "url": "https://www.worlddriven.org/api/webhooks/github"
+  },
+  "redirect_url": "https://www.worlddriven.org/auth/callback",
+  "callback_urls": [
+    "https://www.worlddriven.org/auth/callback"
+  ],
+  "setup_url": "https://www.worlddriven.org/setup",
+  "description": "World Driven - Democratic Pull Request Management Through Contribution-Based Voting.\n\nWorld Driven transforms how open source projects handle pull requests by implementing a fair, transparent, and automated merge system based on contributor participation.\n\nHow It Works:\n- Pull requests are automatically merged after a configurable time period (default: 10 days)\n- Contributors can vote on PRs through GitHub's native review system\n- Approve a review to speed up the merge\n- Request Changes to slow it down or block the merge\n- Vote weight is proportional to contributions to the project\n\nPerfect for open source projects with distributed maintainership, teams wanting democratic code review processes, and communities prioritizing contributor empowerment.",
+  "public": true,
+  "default_events": [
+    "pull_request",
+    "pull_request_review",
+    "push"
+  ],
+  "default_permissions": {
+    "checks": "write",
+    "contents": "write",
+    "issues": "write",
+    "metadata": "read",
+    "pull_requests": "write",
+    "statuses": "write",
+    "workflows": "write"
+  }
+}