Get started: connect GitHub and reach first doc value

Overview Connect your GitHub repository to Moxie, let Moxie index your codebase, and review your first generated docs and drift opportunities. This guide uses plain language and on-screen names to get you to first value in minutes.

What you’ll do

• Install the Moxie GitHub App for your workspace
• Link your first repository
• Trigger the initial index
• Browse generated docs and try search/Q&A
• Review documentation PR opportunities (drift) and manage them
• Optional: set your Docs home view preferences

Before you start

• You need a GitHub account with permission to install apps or request installation on the target repository.
• Sign in to your Moxie workspace.

1. Install the Moxie GitHub App

1. Sign in to Moxie and go to the Dashboard.
2. Select Connect GitHub or start from the GitHub button at /auth/github.
3. When GitHub opens, choose Install for your account or organization.
4. On the “Repository access” screen, pick:
   • All repositories (fastest), or
   • Only select repositories (choose the one you want to start with).
5. Approve the installation. You’ll return to Moxie.

2. Link your first repository to Moxie

1. In Moxie, open Account or Repository settings.
2. Find Repository pickers and choose the GitHub repository you just authorized.
3. Confirm the link. Moxie will prepare to index the repo for docs, search, Q&A, and automation.

3. Trigger the initial index

1. After linking, Moxie begins indexing automatically. If you see an Indexing or Preparing status, leave the page open or come back shortly.
2. If indexing paused due to access changes, re-run the GitHub connect flow from /auth/github and ensure the repository is selected.
3. Once indexing completes, you’ll see docs content available in the Docs workspace.

4. Browse your generated docs

1. Go to Docs in your workspace.
2. Use the search bar at the top (or open the search panel) to find topics across your repository’s document pages.
3. Open Docs home to see collections like Onboarding, Conventions, and Generated docs.
4. Skim a few pages to get a feel for structure and terminology. Generated docs are readable and tied to your current codebase.

5. Try Q&A and give quick feedback

1. In Docs, ask a question using the Q&A input (for example, “Where are API routes documented?”).
2. Review the answer. If it helped, use the thumbs-up; if not, use the thumbs-down and select a tag like outdated or missing_context, and add a short comment. Your feedback improves results over time.

6. Review documentation PR opportunities (drift) Moxie detects when docs fall behind code and proposes focused changes. Cosmetic churn is suppressed.

1. Open the Docs dashboard.
2. Look for PR opportunities cards. Each card summarizes a finding such as stale docs, thin coverage, orphaned pages, undocumented APIs, or convention mismatches.
3. Use the card’s overflow menu to take an action:
   • Open or review the proposed doc PR
   • Dismiss the finding (hides it)
   • Mute for a period if you want to revisit later
4. If you administer automation, open Account → Repository automation to toggle detector kinds for this repository (enable/disable categories that matter to your team).

7. Set your Docs home preferences (optional)

1. From Docs home, hover a collection card (for example, Generated docs or Conventions).
2. Use Favorite or Hide to personalize your view for this repository. Your choices are saved per user.

Tips for a smooth first run

• If you don’t see your repository in the picker, revisit the GitHub App screen and grant access to that repository, then return to Account or Repository settings.
• If you removed the app or changed scopes, reconnect from /auth/github.
• For teams using AI agents: Moxie exposes an MCP surface so tools can pull live repo conventions and propose doc updates in the same PR. You’ll see guidance blocks in PRs when enabled by your team.

You’re done You’ve connected GitHub, completed the first index, browsed generated docs, searched your knowledge, and reviewed initial drift opportunities. Keep Moxie open as you work—new changes will surface as PR opportunities to keep documentation accurate and useful.