docs: remove undocumented features and fix platform documentation (#106)

* docs: remove undocumented features and fix platform documentation

  Remove export docs, organization hierarchy references, and PAT-based
  GitHub auth that don't reflect the actual platform. Simplify git
  integration to document the OAuth app flow via Secrets Manager.

  The changes:
  - Delete export.md (feature doesn't exist)
  - Rename organizations-and-projects.md → projects.md (remove org hierarchy)
  - Simplify git integration to document actual OAuth/Secrets Manager flow
  - Remove "Create an organization" step from first-spec guide
  - Update nav in zensical.toml

* update github integration description with changes introduced in PR #69

Author: JWThewes

docs/getting-started/first-spec.md

@@ -8,12 +8,6 @@ Before starting, make sure you have completed the [Setup](setup.md) steps and ca
 
 Open your deployed application URL (the CloudFront domain from your deployment). Sign in with your Cognito credentials.
 
-## Create an organization
-
-On the home page, choose **New Organization**. Enter a name (for example, "My Team") and a URL slug (for example, "my-team"). Choose **Create**.
-
-Organizations are the top-level container. Each organization has its own projects, members, and settings.
-
 ## Create a project
 
 Inside your organization, choose **New Project**. Enter a name and slug. Choose **Create**.

docs/index.md

@@ -57,4 +57,4 @@ In the **Review** phase, review agents evaluate the code from two angles (blind
 
 - [Getting Started](getting-started/prerequisites.md) to set up the platform
 - [How it works](concepts/index.md) to understand the lifecycle and principles
-- [Using the Platform](using-the-platform/organizations-and-projects.md) for day-to-day usage guides
+- [Using the Platform](using-the-platform/projects.md) for day-to-day usage guides

docs/using-the-platform/export.md

@@ -2,78 +2,32 @@
 
 AIDLC Collaborative integrates with GitHub for repository management, issue creation, and status syncing.
 
-## Connecting GitHub
+## Configure GitHub OAuth
 
-There are two ways to connect:
+[Create a GitHub **OAuth App**](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) (not a GitHub App — the flow here expects OAuth App semantics). When prompted, use:
 
-### Personal access token (PAT)
+- **Homepage URL**: `https://$(terraform -chdir=terraform output -raw cloudfront_domain_name)`
+- **Authorization callback URL**: `https://$(terraform -chdir=terraform output -raw cloudfront_domain_name)/github/callback`
 
-Set `GITHUB_TOKEN` in your `.env.local` file:
+Then store the OAuth App's credentials in the Secrets Manager secret that terraform created (replace `your_github_client_id` and `your_github_client_secret` with the actual values):
 
 ```bash
-GITHUB_TOKEN=ghp_your_token_here
+aws secretsmanager put-secret-value \
+  --secret-id $(terraform -chdir=terraform output -raw github_oauth_secret_name) \
+  --secret-string '{"client_id":"your_github_client_id","client_secret":"your_github_client_secret"}'
 ```
 
-This is the simplest option for local development.
+## Selecting a git repo
 
-### OAuth flow
-
-Configure GitHub OAuth credentials in `.env.local`:
-
-```bash
-GITHUB_OAUTH_CLIENT_ID=your_client_id
-GITHUB_OAUTH_CLIENT_SECRET=your_client_secret
-```
-
-Then connect through the Settings page in the UI. The OAuth flow gives per-project token management.
-
-## Adding repositories to a project
-
-1. Navigate to your project page
-2. Open the Git section
-3. Add a repository by entering its GitHub URL (for example, `https://github.com/owner/repo`)
+1. Click "Create new Project" in the project overview screen
+2. The platform will check if you're connected to GitHub
+3. Select the repository that should back this new project
 
 The repository is cloned into the workspace and becomes available to the LLM assistant and agents.
 
-## Local repositories
-
-You can also link local git repositories on the server machine:
-
-1. Choose **Browse** to open a folder picker
-2. Select a folder that contains a `.git` directory
-3. The local repo is linked by path (no cloning needed)
-
 Local repos are useful during development when you want agents to work on the same codebase you are working on.
 
-## Spec-scoped repos
-
-You can assign specific repos to a spec. This tells the system:
-
-- Which repos the LLM assistant should focus on
-- Which repos the Construction Agent should target
-- Where agents should create worktrees
-
-For each spec-repo association, you configure:
-
-- **Base branch** (for example, `main`)
-- **Feature branch pattern** (for example, `feature/{specSlug}/{taskSlug}`)
-
-## Pushing tasks as GitHub Issues
-
-After running Inception:
-
-1. Choose **Create Issues** in the sprint view
-2. Select the target repository
-3. Tasks are created as GitHub Issues
-
-Each issue includes:
-
-- The task title and description
-- Acceptance criteria as a checklist
-- Test requirements
-- Dependencies listed as issue references
-- A complexity label (for example, `complexity:M`)
-
-## Syncing issue status
+## Reviews
 
-After issues are created, you can sync their status from GitHub. This updates the task status in AIDLC Collaborative based on whether the GitHub issue is open, closed, or has a linked pull request.
+The platform will create a pull request once it is finished with the construction phase. You can start a review. The
+platform will store review results as a comment on the pull request.

docs/using-the-platform/git-integration.md

@@ -0,0 +1,34 @@
+# Organizations and Projects
+
+AIDLC Collaborative uses a project based approach to work.
+
+## Projects
+
+A project groups related specs together. It represents a product, service, or feature area.
+
+Each project has:
+
+- A unique slug within the organization
+- Members with project-level roles
+- Git repository connections
+- Specs
+
+### Creating a project
+
+Navigate to your organization and choose **New Project**. Enter a name and slug.
+
+### Project roles
+
+| Role | Can do |
+|------|--------|
+| **Admin** | Manage project members, settings, and repos |
+| **Editor** | Create and edit specs, run inception, start agents |
+| **Viewer** | Read-only access to specs and tasks |
+
+### Permission resolution
+
+When a user accesses a project, their effective role is resolved in this order:
+
+1. Check if the user has an explicit project role
+2. If not, fall back to their org role (owner/admin become project admin, member gets no access)
+3. If neither, access is denied

docs/using-the-platform/organizations-and-projects.md

@@ -26,7 +26,6 @@ nav = [
         "using-the-platform/running-agents.md",
         "using-the-platform/reviewing-work.md",
         "using-the-platform/git-integration.md",
-        "using-the-platform/export.md",
     ] },
     { "Roadmap" = "roadmap/index.md" },
 ]