# Docs, for Moxie Docs Full Help Center Documentation AI-generated, codebase-grounded documentation for Docs, for Moxie Docs. --- ## Article: Account and email preferences URL: https://docs.moxiedocs.app/documentation/feature_overview/account-and-email-preferences Section: documentation ## Overview Use Account settings to control which product emails Moxie Docs sends you, and to permanently delete your account when you're done. Notification changes apply immediately across every workspace you belong to. ## When to use it - Turn off the weekly recap if it's noise for you. - Turn on nudges so you notice documentation PRs that are ready to review. - Manage marketing and product-update emails separately from product notifications. - Permanently delete your account and remove your personal data. ## How to use it 1. **Open Account settings**, then go to the Notifications & emails tab. 2. **Choose your product emails.** Two toggles are available: - **Friday Recap emails** — a weekly summary whenever a recap exists for a workspace you belong to. - **Documentation nudges** — a notification when documentation PRs are ready for you to review. 3. **Click** Save email preferences. 4. **Manage marketing emails separately**, further down the same page — these are tips and product updates, independent of the recap and nudge toggles above. 5. If you want to delete your account, **go to** the Data controls tab instead. 6. **Open** the "Delete your Moxie Docs account" section. 7. **Type** your account email into the confirmation field exactly as shown, then **click** Delete account. This takes effect immediately — there is no follow-up email link to click. ## Options and settings - Friday Recap emails: On/Off. Weekly summary of recent documentation and PR activity. - Documentation nudges: On/Off. Notifies you when a documentation PR needs review. - Marketing & product emails: Managed separately from the two toggles above. - Delete your Moxie Docs account: Removes you from shared workspaces, cancels billing for any solo workspace you own, deletes your user record, and signs you out. ## Tips - Every recap email includes a one-click unsubscribe link if you'd rather stop it from there. - Turning off both toggles doesn't hide activity in the dashboard — you can still review everything in Moxie Docs anytime, you just won't get emailed about it. - Account deletion is immediate and cannot be undone. Anyone can delete their own account; nobody can delete it on your behalf. --- ## Article: Activate and index a repo URL: https://docs.moxiedocs.app/documentation/feature_overview/activate-and-index-a-repo Section: documentation ## Overview Activate Docs to turn a connected GitHub repository into an organized, searchable knowledgebase. Use the first‑index view to start the initial index, watch progress in real time, and run or cancel jobs as needed. When indexing completes, you can browse collections, search generated pages, and use drift findings to keep docs fresh. ## When to use it - You connected a GitHub repository and want Docs to generate pages for the first time. - You need to queue and run the first indexing job after activation. - You want to monitor indexing status and see when content is ready. - You need to re‑run a queued job once to finish setup. ## How to use it 1. **Open** the repository in Moxie Docs. If the repo has no docs yet, you’ll see the first‑index view with a Status header. 2. **Click** “Activate Repo” to enable Docs for this repository. If you don’t have permission, you’ll see a link to repository settings so someone with the right access can activate it. 3. **Click** “Activate & Queue” to both activate and place the first index in the queue. This prepares the job to run. If the repo is already activated, you may only see queue and run controls. 4. **Click** “Run queued job once” to start the first index. The Status header auto‑refreshes while the job is queued or running. 5. **Watch** the Status header for live updates. Stay on the page while it auto‑refreshes; you can come back later if needed. 6. **Wait** for indexing to complete. When done, browse collections and search across generated pages from the dashboard. Review drift findings to spot outdated docs and create PRs to update them. 7. **Re‑run** if needed. If the job is still queued or you need a single fresh run, click “Run queued job once” again. If you don’t have access to run jobs, follow the on‑screen link to repository settings or contact a manager. ## Choose the indexing branch By default, Moxie Docs indexes and generates documentation from your repository’s default branch on GitHub (usually `main`). If your team develops on a separate branch—such as `develop` or `staging`—you can point Moxie Docs at that branch instead, without changing your repository’s default on GitHub. 1. **Open** Settings → Repositories in the Dashboard. 2. **Find** the repository and click the **Indexing** branch control beneath its name. 3. **Enter** the branch you want Moxie Docs to read from, then **Save**. Leave the field empty to follow the default branch again. When an indexing branch is set, everything Moxie Docs reads and writes follows it: the source it documents, the files you browse and open on GitHub, inline documentation edits, and the base branch of every documentation pull request. Pushes to that branch trigger re‑indexing, just as pushes to the default branch normally would. Only workspace owners and admins can change the indexing branch, and the branch must already exist in the repository. ## Options and settings - Status header: shows current first‑index status and live updates. - “Activate Repo”: enables Docs for the connected repository. - “Activate & Queue”: activates the repo and places the first indexing job in the queue. - “Run queued job once”: starts a single run of the queued indexing job. - Indexing branch: choose which branch Moxie Docs reads and documents; leave empty to follow the repository’s default branch. Documentation pull requests open against the branch you choose. - Permission‑aware prompts: managers see activation controls; members without permission see a link to repository settings. - Billing‑aware actions: some buttons may be unavailable if your plan does not allow activation or runs. ## Tips - Stay on the first‑index view to watch progress; it auto‑refreshes while work is queued or running. - If you can’t see “Activate Repo,” you likely lack permission—use the repository settings link shown on the page or ask a manager. - After the first index completes, use drift findings to quickly prioritize doc updates before re‑running a job. - You can return to the repo later; the Status header will reflect the latest state when you reopen it. --- ## Article: Admin blog via SnowSEO webhook URL: https://docs.moxiedocs.app/guides/integration_guide/admin-blog-snowseo-webhook Section: guides ## Overview Connect SnowSEO to your Moxie Docs admin blog so new articles sent by SnowSEO arrive as drafts for review. Moxie Docs accepts webhooks from SnowSEO, mirrors referenced images to first‑party storage, and creates draft posts in the internal blog for admins to edit and publish. ## Before you start - A Moxie Docs workspace with access to the Admin CMS at “/admin/blog”. - Admin or editor permissions in Moxie Docs to review and publish blog drafts. - A SnowSEO account with permission to configure webhooks for article delivery. ## Connect 1. **Open** your Moxie Docs site and **navigate** to the Admin CMS at “/admin/blog”. 2. **Locate** the webhook endpoint for SnowSEO: “/api/integrations/snowseo/webhook”. This is the public HTTP URL SnowSEO will call. If your Moxie Docs site is hosted at https://docs.example.com, the full endpoint will be https://docs.example.com/api/integrations/snowseo/webhook. 3. In SnowSEO, **open** the webhook settings for article delivery. 4. **Paste** the full Moxie Docs webhook URL into SnowSEO’s webhook URL field. 5. **Save** the webhook configuration in SnowSEO. ## Configure - Webhook URL: Use your site’s fully qualified URL for “/api/integrations/snowseo/webhook”. - Article handling: Incoming SnowSEO articles are created as drafts in the internal blog for admin review. Moxie Docs mirrors linked images to first‑party storage during ingestion. - Review and publish: Use “/admin/blog” to edit, approve, and publish the new drafts. ## Verify it works - Send a test article from SnowSEO to the configured webhook and confirm a new draft appears in “/admin/blog”. - Open the draft in “/admin/blog” and verify that images render (mirrored to first‑party storage). - Check the draft’s metadata (title, body) matches the SnowSEO payload you sent. - Publish the draft from “/admin/blog” and confirm it renders in your internal blog. ## Disconnect or change access - To stop receiving articles, remove or disable the webhook in your SnowSEO webhook settings. - To point to a different Moxie Docs site, update the webhook URL in SnowSEO to the new site’s “/api/integrations/snowseo/webhook”. - If you change your Moxie Docs host (domain), update the SnowSEO webhook URL accordingly so deliveries continue to reach your site. --- ## Article: Billing, trial, or access issues URL: https://docs.moxiedocs.app/guides/troubleshooting/billing-trial-or-access-issues Section: guides ## Overview This guide helps you resolve common issues starting a trial, updating payment details, and accessing paid features in Moxie Docs. Use the steps below if you cannot activate a repository, start indexing, or open public knowledgebase setup. ## Before you start - Confirm you can sign in to your Moxie Docs workspace. - Check your role: managers can activate repositories and manage billing; members may have limited access. - Make sure your GitHub account is connected and you can access the target repository in GitHub. ## Trial did not start after sign‑up You may expect immediate access to Docs features, but you still see locked actions or prompts to activate billing. 1. **Refresh** the dashboard and open “Docs home” to verify trial status. 2. **Open** the target repository in Moxie Docs and check the first‑index view. If you see “Activate Repo,” your trial or permissions may not be applied to this repo yet. 3. **Click** “Activate Repo” if available. If the button is disabled, **contact** a workspace manager to enable the repo for Docs. 4. **Retry** an index by clicking “Activate & Queue” if activation succeeds but no job has started. 5. **Recheck** your GitHub connection by signing out and back in, then returning to “Docs home.” - If you are a member and see a link to repository settings instead of activation controls, ask a manager to activate the repository. ## Cannot activate a repository You open a repo and the first‑index view shows activation controls are unavailable or blocked. 1. **Verify** your role. If you are not a manager, **ask** a manager to activate the repository. 2. **Confirm** the repository is connected to your workspace and visible on “Docs home.” If it is missing, **ask** a manager to connect it. 3. **Click** “Activate Repo” to enable Docs. If activation requires billing, **ask** a manager to complete billing and then try again. - After activation, you can start indexing with “Activate & Queue” or run a queued job with “Run queued job once.” ## Indexing is blocked or jobs will not run You see a repo in the first‑index view, but indexing will not start, stays queued, or cancels immediately. 1. **Click** “Activate & Queue” to start the first index. Wait a moment; the view auto‑refreshes while work is queued or running. 2. If a job is queued but not running, **click** “Run queued job once.” 3. If controls are disabled or you see a permission prompt, **ask** a manager to confirm billing is active for this repo and that you have access. 4. **Return** to “Docs home” and try opening a collection after the index completes. - Empty search results while indexing is pending are expected; content appears after the first successful index. ## Paid collections or search appear empty You can open “Docs home,” but collections are empty or search returns no results. 1. **Confirm** the first index completed. **Open** the repo’s first‑index view and check that no job is running or queued. 2. If no content has been indexed, **click** “Activate & Queue.” 3. After indexing completes, **open** a collection from the collection grid to confirm pages are available. - Empty queries in the search bar return no results; try entering a specific term. ## Public knowledgebase setup is unavailable You expect to create a public knowledgebase, but you do not see the onboarding wizard or settings. 1. **Check** with a workspace manager that the public knowledgebase feature is enabled for your organization (beta, gated by a feature flag). 2. **Ask** a manager to open the knowledgebase onboarding wizard and reserve a subdomain. 3. **Confirm** the docs source and visibility defaults during setup, then **save** settings. - If the feature is not enabled for your org, your manager can request access to the beta. ## Cannot reserve a subdomain for the public knowledgebase During the wizard, subdomain validation fails or you cannot complete reservation. 1. **Re‑enter** the desired subdomain and wait for validation to complete. 2. **Choose** a different subdomain if the first is taken or invalid. 3. **Save** to create the org‑scoped knowledgebase record after validation succeeds. ## Drift review and PR creation are unavailable You try to use the search bar for drift review or create PRs, but actions are disabled or nothing appears. 1. **Verify** the repository has been indexed at least once; drift findings appear only after content exists. 2. **Search** with a relevant term to surface findings; empty queries return no results. 3. If PR actions are disabled, **confirm** your GitHub access to the repo and **ask** a manager to ensure the repo is activated for Docs. ## Email preferences are not saving You try to opt into weekly recaps or documentation nudges, but your choices do not stick. 1. **Open** account settings and locate the email preferences form. 2. **Update** your selections and **save**. Wait a moment, then **refresh** the page to confirm they persist. 3. If changes do not save, **sign out and back in**, then retry. ## Friday Recap is missing from the dashboard You expect a weekly recap but do not see it in the dashboard. 1. **Check** that your email preferences include weekly recaps. 2. **Confirm** at least one repository is activated and has recent activity or doc changes. 3. If your workspace uses the planned Slack integration, note that posts appear only after your admin completes the “Add to Slack” flow. ## Still need help - Recheck your role and that the target repository is activated for Docs and indexed at least once. - Ask your workspace manager to verify billing status and feature access for your organization. - If the issue persists, contact your workspace admin with the repository name, what you clicked, and any on‑screen text from the first‑index view or knowledgebase wizard. --- ## Article: Changelog from PRs URL: https://docs.moxiedocs.app/documentation/feature_overview/changelog-from-prs Section: documentation ## Overview Changelog from PRs builds a shareable release or sprint changelog from your merged GitHub pull requests. Moxie Docs creates AI summaries for each merged PR, lets you edit or hide entries, and tag them by audience and category. You can preview the timeline, copy preset sections for reuse, and export when you’re ready to share. This feature is for maintainers and docs owners who want a clean, readable list of changes without digging through GitHub. Start from the Docs dashboard, review the generated timeline, make your adjustments, and publish your chosen format. ## When to use it - Summarize a sprint or release from merged PRs without manual sorting - Prepare internal notes for support, sales, or success teams - Create a public-facing changelog filtered for specific audiences - Cut noise by hiding minor or irrelevant PRs ## How to use it 1. **Open** the Docs dashboard and go to Changelog from PRs for your repository’s timeline. 2. **Scan** the generated entries. Each merged PR appears with an AI summary, date, and linked PR reference. 3. **Edit** any summary to clarify wording. Select the entry, update the text, and save. 4. **Tag** an entry by audience and category to group similar changes. Choose the audience and category that fit how you plan to share updates. 5. **Hide** noise. Mark entries you don’t want to include in this release so they won’t appear in your export. 6. **Preview** your changelog to see how the timeline will read when shared. 7. **Copy** a preset if you want a standard layout or set of sections for your release notes. Apply the preset to organize entries quickly. 8. **Export** the changelog. Choose your preferred export to share with your team or publish externally. 9. **Repeat** as needed. Older items are auto-archived past the retention window, keeping the timeline focused on recent work. ## Options and settings - Changelog timeline: View merged PRs in chronological order for the connected repository. - Edit summary: Override the AI summary with your own wording. - Audience: Tag who the change is for (for example, end users, admins, or internal teams). - Category: Tag what type of change it is (for example, fix, improvement, or doc update). - Hide entry: Exclude selected items from previews and exports. - Preview: See the assembled changelog before sharing. - Copy presets: Reuse a saved structure for consistent release notes. - Export: Produce a shareable output of the current selection and order. ## Tips - Start by tagging audience and category before editing text. It helps you spot gaps and balance the release narrative. - Use Hide for dependency bumps or internal refactors that don’t impact readers. - Keep edits concise—aim for one sentence per entry so the changelog stays scannable. - If an entry looks off, check the linked PR to confirm scope, then update the summary once for future exports. --- ## Article: Changelog timeline and overrides URL: https://docs.moxiedocs.app/documentation/feature_overview/changelog-timeline-and-overrides Section: documentation ## Overview The Changelog page keeps a running log of what shipped in a repository — merged pull requests and direct commits, summarized and split by audience. Review each entry, edit anything that reads wrong, and publish it to your repo's public "What shipped" page. ## When to use it - You want a plain-English history of what changed, not a raw commit log. - You need to review AI-written summaries before they go public. - You want to filter history down to what a specific audience cares about. - You want to share a set of recent changes somewhere other than the changelog page itself. ## How to use it 1. **Open** the Changelog page for your repository. 2. **Filter by Publish status** — Review, Published, Unpublished, or All — to find the entries you need. 3. **Filter by Audience** — All, External, or Internal — to see changes relevant to a specific readership. 4. **Group and filter further** using Group by, Category, and the date range controls. 5. **Review a draft entry.** Entries awaiting review are flagged; open one and edit the summary if it doesn't read right. 6. **Publish or unpublish** entries individually, or select several and use the bulk actions when in Review mode. 7. **Copy entries elsewhere** using the copy menu at the top: Markdown, Slack / Discord, or Plain text — all copy straight to your clipboard. 8. **Include archived entries** with the "Include archived" checkbox if you need to look further back. ## Options and settings - Publish status: Review, Published, Unpublished, or All. - Audience: All, External, or Internal. - Group by / Category: Change how entries are organized and filtered. - Link PRs: Toggle whether entries link back to their source pull request. - Include archived: Show entries that have moved out of the default view. - Copy formats: Markdown, Slack / Discord, or Plain text — copies the current view to your clipboard. ## Tips - Low-confidence summaries are flagged for review — check those before publishing rather than trusting them by default. - Editing an entry only changes how it reads; it doesn't change the underlying merged PR or commit. - Use Audience filtering before you copy or share a changelog snippet, so internal-only entries don't leak into an external update. --- ## Article: Configure PR automation and detectors URL: https://docs.moxiedocs.app/guides/integration_guide/configure-pr-automation-and-detectors Section: guides ## Overview This guide helps you tune how Moxie Docs surfaces documentation drift and how those findings become clear, low‑noise pull requests in your GitHub repository. After setup, you can review focused suggestions, preview changes, and create PRs that update or remove outdated docs with confidence. ## Before you start - A connected GitHub repository that Moxie Docs can read and open pull requests against. - Access to the Moxie Docs dashboard for your workspace. - Permission in your GitHub repo to create branches and pull requests. ## Connect 1. **Open** the Moxie Docs dashboard and **go to** your documentation collections. 2. **Confirm** your GitHub repository is connected. If the repo is not connected yet, **follow** the GitHub connection prompt shown in the dashboard to authorize access so Moxie Docs can create pull requests. 3. **Wait** for the initial index to finish so documentation pages appear in search and drift review. ## Configure Use drift review and search to focus findings and shape PRs before you create them. - Use the search bar on Docs Home or any collection view to find pages and drift by keyword. Empty searches return no results, so enter a term related to the area you want to update. - In drift review, look at each finding’s type and severity to decide whether to act now or later. - For items you do not want to see again, dismiss or mute them to reduce noise in future review sessions. - When a suggested PR appears, open it to preview the exact documentation changes before creating the PR in GitHub. - For outdated docs that should be removed instead of updated, choose the option to remove outdated docs when reviewing suggestions so the PR focuses on deletions. - Keep the list of suggested and open PRs short by regularly dismissing low‑value items and acting on high‑severity findings. ## Verify it works - You can search for a topic and see relevant documentation pages along with drift findings by type and severity. - The drift review shows suggested PRs that you can open and preview. - Creating a PR from the preview results in a new pull request in your GitHub repository. - Dismissing or muting an item removes it from your active review list on refresh. ## Disconnect or change access - To stop creating documentation PRs from Moxie Docs, revoke its access in your GitHub account and remove the repository connection in the Moxie Docs dashboard. - If you need to switch repositories, disconnect the current repo in the dashboard, then connect the new GitHub repo and allow indexing to complete before reviewing drift again. --- ## Article: Delete your account and feedback URL: https://docs.moxiedocs.app/documentation/feature_overview/delete-your-account-and-feedback Section: documentation ## Overview Use account deletion to permanently remove your access to Moxie Docs and erase your personal Q&A feedback. This protects your privacy while respecting your organization’s rules for workspace membership and content. After deletion, you won’t be able to sign in or see your team’s knowledgebase, Friday Recaps, or Q&A history tied to your account. ## When to use it - You’re leaving the organization or no longer need Moxie Docs. - You want your personal Q&A feedback removed for privacy. - You need to ensure your user access to workspaces is fully revoked. ## How to use it 1. **Open** the Moxie Docs dashboard and select your avatar in the top-right corner. 2. **Click** Account to open your account settings. 3. **Scroll** to the bottom of the page and **select** Delete account. 4. **Review** what will be removed and what your organization keeps, as shown in the confirmation dialog. 5. **Confirm** by typing the requested confirmation text (if prompted) and **click** Delete account. 6. **Check** your email for a confirmation (if sent). Once processed, you’ll be signed out and lose access to all connected workspaces. ## What’s removed and what stays - Your Moxie Docs user account is deleted. You can’t sign back in with it. - Your membership in any workspaces is removed, subject to your organization’s rules. Some orgs may retain minimal records of past membership for auditing. - Your Q&A feedback comments and reactions are erased to protect your privacy. This includes feedback you left on AI answers and changelog entries. - Team content like repos, docs, knowledgebase articles, Friday Recaps, PRs, drift alerts, and automation settings are not deleted. These belong to the organization and remain for other members. ## Options and settings - Delete account: Starts the deletion flow and shows a summary of what will be removed. - Organization rules: If your org enforces retention or audit logs, you may see a notice explaining what minimal records can remain (for example, the fact that a user once existed, without Q&A feedback details). ## Tips - If you only want to stop notifications, adjust your notification settings instead of deleting your account. - If you belong to multiple workspaces, deletion removes you from all of them in one step. - You can’t recover erased Q&A feedback after deletion. Consider exporting any personal notes before you proceed. - If you think you’ll need access again later, ask your admin whether deactivation is available as an alternative. --- ## Article: Docs Home and collections URL: https://docs.moxiedocs.app/documentation/feature_overview/docs-home-and-collections Section: documentation ## Overview Docs Home shows your repository’s generated documentation organized into labeled collections, such as Get started, Architecture, or Backend. It’s for anyone who needs to quickly browse what Moxie Docs has indexed and open pages once content is available. From here you can mark favorite collections, hide ones you don’t use, and jump into pages as soon as indexing finishes. ## When to use it - You want a quick, organized view of your docs by topic. - You need to find and open generated pages after indexing completes. - You want to favorite high‑value collections to keep them handy. - You prefer to hide collections that aren’t relevant to your work. ## How to use it 1. **Open** the Dashboard and go to Docs Home. You’ll see a grid of labeled collections for your repository. 2. **Browse** the collection grid to scan topics. Each tile represents a collection generated from your code and docs. 3. **Check** indexing status. Collections and pages are available to open once indexing has content. If a collection is still empty, come back after indexing completes. 4. **Open** a collection to view its pages. Select a collection tile to see the generated pages inside it. 5. **Open** a page. Choose a page from the list to read the generated documentation. 6. **Favorite** a collection you use often. Select the Favorite control on the collection to keep it easy to find. 7. **Hide** a collection you don’t need. Select the Hide control to remove it from your default view. You can return later and show it again from the same control. ## Options and settings - Favorite: Pin a collection you use frequently so it’s easier to spot in the grid. - Hide: Remove a collection from your default view without deleting any documentation. - Indexing status: Collections and their pages become available to open once indexing has content. ## Tips - If a collection looks empty, indexing may still be running or no matching content was found yet. Check back after indexing completes. - Favoriting and hiding affect only your view and do not change the underlying documentation. - Use clear collection labels (like Get started or Backend) to quickly narrow down where your page is likely to be. --- ## Article: Drift detection and PR automation URL: https://docs.moxiedocs.app/documentation/feature_overview/drift-detection-and-pr-automation Section: documentation This page shows you how to review drift findings in Moxie Docs, understand severities, and safely generate or review pull requests (PRs) that keep your documentation in sync with your code. You will learn where to find documentation opportunities, how to mute or dismiss items, and how to control automation per repository. ## What Moxie Docs flags as drift Moxie Docs watches your connected GitHub repository and compares the codebase to your docs. When something no longer lines up, you’ll see a documentation opportunity. Moxie Docs classifies these by type and severity. - Drift types: stale, thin, orphaned, undocumented‑API, convention‑mismatch - Severity levels: - Breaking: likely to confuse or mislead readers because behavior or interfaces changed - Behavioral: behavior changed or expanded, but not fully breaking - Cosmetic: wording, tone, or minor format differences that don’t affect meaning (Moxie Docs never opens PRs for cosmetic drift) ## Where to review drift You can review drift and potential updates in two places: - Dashboard → Documentation opportunities: Cards list findings with type and severity. Use these cards to review, dismiss, or mute items. - Dashboard → Docs PR opportunities: Suggested and open PRs that Moxie Docs can create or has created to update, align, or remove docs. ## Review and act on documentation opportunities Use this flow to decide what to change now and what to ignore for later. 1. **Open** Dashboard → Documentation opportunities. 2. **Scan** the cards for severity labels (Breaking, Behavioral, Cosmetic) and drift types (stale, thin, orphaned, undocumented‑API, convention‑mismatch). 3. **Click** a card to view details, including what changed and which docs are affected. 4. **Choose** an action from the card’s overflow menu (three dots): - Dismiss: remove the item from your queue now. - Mute: hide the item for a while so it doesn’t create noise. 5. **Decide** whether to let Moxie Docs generate a PR or handle it later. Cosmetic items never generate PRs. ## Generate or review PRs that update docs When drift is significant, Moxie Docs can open a scoped PR to fix or remove outdated docs. 1. **Open** Dashboard → Docs PR opportunities. 2. **Select** a suggested PR to preview the proposed doc changes. 3. **Review** the summary and changed files to ensure they match the current code behavior. 4. **Click** Create PR (or similar action) to open the pull request in your connected GitHub repository. 5. **Follow** your normal review process in GitHub to approve and merge. Moxie Docs tracks the change in your workspace changelog. Notes: - Moxie Docs never opens PRs for cosmetic drift. - PRs are scoped to the docs affected by the specific drift finding. ## Tune automation per repository Control how much Moxie Docs automates for each repo so your team sees the right level of change. 1. **Open** Account/Repository settings. 2. **Locate** Automation settings for the selected repository. 3. **Toggle** detectors on or off for drift types you care about (stale, thin, orphaned, undocumented‑API, convention‑mismatch). 4. **Choose** whether Moxie Docs should propose PRs automatically for non‑cosmetic drift, or require manual review first. 5. **Save** your changes. ## Tips for a smooth review process - Start with Breaking items, then Behavioral. Leave Cosmetic for routine cleanup. - Use Mute on noisy patterns you plan to address later; use Dismiss when the finding is not relevant. - Keep detectors enabled only for the drift types that matter to your docs today. - Check Docs PR opportunities regularly to keep your docs current with minimal effort. --- ## Article: Friday Recap and weekly updates URL: https://docs.moxiedocs.app/documentation/feature_overview/friday-recap-and-weekly-updates Section: documentation ## Overview Friday Recap highlights the week’s most important documentation and code changes pulled from your connected GitHub repositories. You’ll see a short summary with an impact line, plus links back into Moxie Docs to review suggested doc updates and recent PR-driven changelog entries. You can optionally receive these weekly highlights in Slack or by email, and you can dismiss on-screen recap prompts you don’t need. You control weekly recap emails and documentation nudges from your account’s email preferences. ## When to use it - Stay on top of doc drift and code changes without checking every repo. - Share weekly highlights with your team in Slack. - Quickly decide which suggested doc updates to review or approve. - Reduce noise by dismissing recap prompts you’ve already handled. ## How to use it 1. **Open** the Docs dashboard. You’ll find Friday Recap cards showing the week’s highlights with an impact line. 2. **Scan** the recap summary. Look for items like suggested doc PRs, recent changelog entries from merged code, and flagged drift. 3. **Click** any recap item to review details. From there, you can open suggested doc PRs, read changelog notes, or continue to related Q&A. 4. **Decide** what needs action. Approve or request changes on suggested doc updates, or mark items as reviewed in your normal docs workflow. 5. **Dismiss** a recap prompt if you’re done. Use the dismissal on the recap card to remove it from view. 6. (Optional) **Enable** Slack notifications so weekly highlights post to your team’s Slack. Use your Slack integration and confirm you want Friday Recap updates delivered there. 7. (Optional) **Manage** email delivery for weekly recaps and documentation nudges. Open your account settings and update your email preferences to receive or stop these messages. ### Receive Slack or email notifications 1. **Enable** Slack notifications if your team wants updates in a channel. Once enabled, Friday Recap highlights will be sent to Slack each week. 2. **Update** email preferences in your account settings to receive weekly recaps and documentation nudges, or to turn them off. ## Options and settings - Friday Recap cards: show weekly highlights with an impact line and links to details. - Dismiss recap: remove a recap prompt you no longer need. - Slack notifications: optional delivery of weekly highlights to Slack when your Slack integration is enabled. - Email preferences: control weekly recaps and documentation nudges delivered by email from your account settings. ## Tips - If you don’t see a Friday Recap, check back at the end of the week or confirm your GitHub repository is connected to Moxie Docs. - Dismissing a recap only affects your view; you can still access underlying items from the Docs dashboard (e.g., changelog, suggested doc PRs). - Keep email recaps on if you’re away from the dashboard often; turn them off if you rely on Slack instead. --- ## Article: Give feedback on answers URL: https://docs.moxiedocs.app/documentation/feature_overview/give-feedback-on-answers Section: documentation This page explains how to rate answers in the Docs Q&A panel and share context with tags and comments. You’ll learn how your feedback improves answer quality over time. ## Where you can leave feedback You can leave feedback directly under any answer in the **Docs Q&A** panel using the inline feedback widget. Each rating is attached to the specific answer it appears under. ## Submit a thumbs up or thumbs down Use thumbs to quickly show whether an answer helped. 1. **Open** the **Docs Q&A** panel in your Moxie Docs workspace. 2. **Ask** a question or **select** an existing question to view its answer. 3. **Click** the **Thumbs up** icon if the answer is helpful, or **Thumbs down** if it isn’t. ## Add tags and a comment Tags and comments help your team understand what worked and what didn’t. 1. **Choose** one or more tags from the tag list that appears after you rate. Examples include accuracy, completeness, clarity, or relevance (availability may vary by workspace). 2. **Type** an optional comment to explain why you chose that rating. Be specific about what was correct, missing, or confusing. 3. **Click** **Submit** to save your feedback. Tips for useful comments: - Point to a specific sentence or section that was helpful or incorrect. - Note what you expected to see, such as missing setup steps or outdated behavior. - Include keywords from your question so others can find similar feedback. ## How your feedback is used Your feedback is tied to the original answer in the Q&A panel, so teams can review ratings alongside the response you saw. Over time, this helps: - Measure answer quality across questions and repos. - Identify common issues (for example, unclear steps or out-of-date details). - Guide updates to generated docs and Q&A behavior so future answers improve. ## Edit or change your feedback If you need to correct your input: 1. **Return** to the same answer in the **Docs Q&A** panel. 2. **Click** the opposite thumb to change your rating, or **update** your tags and comment if the widget allows editing. 3. **Submit** your changes. ## Troubleshooting - If you don’t see the feedback widget, make sure you are viewing an answer in the **Docs Q&A** panel and are signed in to your workspace. - If tags don’t appear after rating, try refreshing the page and rate again. - For ongoing issues, contact your workspace admin to confirm your plan and permissions support Q&A feedback. --- ## Article: Integration: connect an MCP-capable agent URL: https://docs.moxiedocs.app/guides/integration_guide/integration-connect-an-mcp-capable-agent Section: guides ## Overview Connect an MCP-capable agent to Moxie Docs so your own automation or assistant can ask grounded questions about your repositories and use the same context Moxie Docs uses. After setup, your MCP client can route questions to Moxie Docs’ “Ask this codebase” and reflect feedback to improve answers over time. Nothing is changed in your repositories without your review; Moxie Docs continues to only open documentation pull requests that you approve. ## Before you start - A Moxie Docs workspace with at least one connected GitHub repository. - Access to Moxie Docs with permission to view Docs and Ask panels. - An MCP-capable client or agent you control (for example, an automation or assistant that supports MCP tools). - The ability to adjust settings in your MCP client. ## Connect 1. **Open** Moxie Docs and go to Docs. 2. **Select** the repository you want your agent to use for Q&A. 3. **Open** the Ask panel. This is where “Ask this codebase” lives and where feedback is captured. 4. **Review** the scope shown in the Ask panel so you know which repository and branch your agent will be able to query through Moxie Docs. 5. **Open** your MCP-capable client and **add** a new tool or data source that connects to Moxie Docs for Q&A. Use your client’s standard flow to enable a tool that can ask questions and read answers. 6. **Return** to the Ask panel in Moxie Docs and **submit** a simple question to confirm the repository context looks right. Keep this tab open so you can compare results from your agent. Note: If your MCP client prompts you to choose what the agent can access, select the repository you opened in the Ask panel so questions stay grounded in that codebase. ## Configure After connecting, set how the agent should use Moxie Docs: - Choose repository scope: Limit the agent to the repository you selected in the Ask panel for focused answers. - Set question style: Encourage specific questions (for example, “Where is the auth middleware registered?”) to get targeted results. - Enable feedback: Have the agent record thumbs up/down for each answer using the Ask panel’s feedback widget so Moxie Docs can learn from your usage. - Add tags on feedback: Standardize tags (for example, “correctness”, “missing context”) so trends are easy to review later. ## Verify it works - Ask from your MCP client: Submit a question through your agent and confirm the answer matches what you see when you ask the same question in the Ask panel in Moxie Docs. - Check feedback capture: In the Ask panel, use the thumbs widget on the answer your agent referenced and apply a tag. Confirm your agent can reflect that outcome in its next interaction. - Validate repository grounding: Ask a question that only your selected repository can answer (for example, about a specific file or function name) and confirm the response references that codebase. - Confirm no changes occur: Ensure your agent’s use of Q&A does not create pull requests. Documentation pull requests are only opened by Moxie Docs drift detectors and require your review and merge. ## Disconnect or change access - To change which repository the agent uses, open Docs, switch to the desired repository, and use the Ask panel there. Update your MCP client to point to that repository’s context. - To stop your agent from using Moxie Docs Q&A, remove the Moxie Docs tool or data source in your MCP client. - If you no longer want the agent’s feedback to affect learning, stop submitting thumbs up/down in the Ask panel or remove tags before saving feedback. --- ## Article: Integration: MCP agents URL: https://docs.moxiedocs.app/guides/integration_guide/mcp-agents Section: guides ## Overview This integration connects a Model Context Protocol (MCP)–capable agent to your Moxie Docs knowledgebase. After setup, your agent can read repository conventions captured by Moxie Docs, search across generated documentation, and assist with drift review and preparing updates that you can turn into PRs in your GitHub repo through the Moxie Docs dashboard. ## Before you start - A Moxie Docs workspace connected to your GitHub repository. - Access to the Moxie Docs dashboard for your workspace. - An MCP-capable agent that can read from external knowledge sources you provide (for example, by following links you share). - Permission to share read-only links or content snippets from your Moxie Docs knowledgebase with your agent. ## Connect 1. **Open** the Moxie Docs dashboard and go to your Docs home. You should see the search bar and your collections. 2. **Locate** the repository conventions and documentation you want your MCP agent to use. You can browse collections or use the search bar on Docs Home and collection views. 3. **Share** the relevant page links or content with your MCP agent. Provide the agent with the URLs to the Moxie Docs-generated pages or paste the content you want it to reference. If your agent supports following links, give it the page links directly; otherwise, supply the text content. 4. **Explain** to your agent how to use the knowledgebase: that it can query the same documentation you see in Moxie Docs and that drift findings indicate where docs may need updates. Point it to the pages that contain your conventions and any drift review summaries you plan to act on. Note: Moxie Docs is the system of record. Your MCP agent reads what you share; creating and merging PRs still happens in Moxie Docs and GitHub. ## Configure - Scope: Share only the pages or collections your agent needs (for example, coding conventions, API usage guides, runbooks). - Search behavior: Use Moxie Docs’s search bar in the dashboard to find high-signal pages. Provide those links or excerpts to your agent for context. - Drift review: Include links or excerpts that show drift findings (type and severity) so your agent can help you draft updates. - Feedback loop: When the agent suggests changes, plan to preview and create PRs through the Moxie Docs dashboard so changes land in your GitHub repo. ## Verify it works - Ask your agent a question that is answered in a Moxie Docs page you shared. Confirm it cites or reflects the conventions from that page. - Provide a link to a page with drift findings and ask the agent to summarize the items by type and severity. Check that its summary matches what you see in Moxie Docs. - Have the agent propose doc updates based on a drift finding. Compare its draft to the source page in Moxie Docs before creating a PR in the dashboard. - Use the Moxie Docs search bar to find a specific topic, share that page with the agent, and confirm it updates its answer using the new context. ## Disconnect or change access - To revoke access, stop sharing links or content with the agent and remove any stored context in the agent’s memory or project history. - To change scope, provide updated page links or replace previously shared excerpts with the new, correct pages from Moxie Docs. - PR creation and review remain in Moxie Docs and GitHub. If you decide not to use the agent’s suggestions, proceed with your usual review in the Moxie Docs dashboard and dismiss or mute drift items as needed. --- ## Article: Manage subscription URL: https://docs.moxiedocs.app/documentation/feature_overview/manage-subscription Section: documentation ## Overview Use Billing/Subscription to start a 14‑day trial, upgrade to a paid plan, or confirm your billing status so Moxie Docs can keep indexing your repo and running automation. Checkout happens in Stripe, and your subscription state syncs back to Moxie Docs automatically. This page helps you start or upgrade your plan, understand what happens during a trial, and verify that your account is active. ## When to use it - You’re new to Moxie Docs and want to start the 14‑day trial. - You need to upgrade to a paid plan so indexing and docs-only PRs continue after the trial. - You want to confirm your current billing status and renewal date. - You need to update payment details so automation doesn’t pause. ## How to use it 1. **Open** the Moxie Docs Dashboard and go to “Billing/Subscription.” 2. **Start your trial** by selecting “Start 14‑day trial” (if you don’t have an active plan). This enables indexing and automation during the trial period. 3. **Upgrade** by selecting “Upgrade” or “Manage plan.” You’ll be taken to Stripe Checkout. 4. **Complete** payment in Stripe Checkout. Add your payment method, review the plan, and confirm. 5. **Return** to Moxie Docs. The subscription status updates automatically via Stripe. You should see “Active” once Stripe confirms payment. 6. **Verify** your status on the Billing/Subscription page. Check the plan name, next charge date, and payment method on file. 7. **Update payment details** anytime by selecting “Manage plan” on Billing/Subscription. You’ll be redirected to Stripe to edit your card or billing info. 8. **Confirm continuity** by ensuring the status is “Active.” Indexing, docs-only PRs, search, and automation continue while your plan is active. ### Understand trial limits 1. **Check your trial countdown** on Billing/Subscription. The page shows how many days remain in your 14‑day trial. 2. **Know what runs during trial:** indexing, documentation generation, and automation run during the trial. 3. **Upgrade before the trial ends** to avoid pauses. If the trial expires without upgrading, indexing and automation may stop until a paid plan is active. ## Options and settings - Plan status: Shows Trial, Active, Past Due, or Canceled, with the next renewal date when applicable. - Start 14‑day trial: Begins your trial if you have no active subscription. - Upgrade / Manage plan: Opens Stripe Checkout to start, change, or cancel a paid plan and update payment details. - Payment method: Displays the card on file once set in Stripe. ## Tips - If you don’t see your status update right away after Stripe Checkout, wait a minute and refresh; webhooks usually sync quickly. - Keep a valid payment method on file to prevent pauses in indexing and docs-only PRs. - If your status shows Past Due, open “Manage plan” to update your card in Stripe, then return and refresh the Billing/Subscription page. --- ## Article: Opportunity cards seem noisy or wrong URL: https://docs.moxiedocs.app/guides/troubleshooting/opportunity-cards-seem-noisy-or-wrong Section: guides ## Overview This guide helps when documentation pages don’t show up in Docs home, content looks stale after a recent commit, or search results lag behind your latest changes. It also shows how to reduce noise in drift findings so you only see opportunities that matter. ## Before you start - You can sign in to your Moxie Docs workspace. - Your GitHub repository is already connected to Moxie Docs. - You can open the Dashboard and see “Docs home.” ## Pages don’t appear in Docs home or collections You land on “Docs home” but expected to see your repository’s pages organized into collections, and some are missing. This can happen right after connecting a repo or when a collection has no indexed content yet. 1. **Open** the Dashboard and go to “Docs home.” 2. **Check** the collection grid for your expected collections. If a collection is hidden, **unhide** it so it’s visible in the grid. - You can browse, favorite, hide, and open collections once indexing has content. 3. **Open** a visible collection you expect to contain the page and **browse** its items. 4. **Search** using the search bar on “Docs home” for the page title or keywords to confirm whether it’s indexed. 5. **Wait** a few minutes if you just connected the repo or made large changes; pages appear after indexing has content. 6. **Verify** that the page actually exists in your GitHub repo; Moxie Docs indexes from your code and docs. ## Content looks stale after a recent commit You edited docs in GitHub, but the page in Moxie Docs still shows the older version. This is usually due to indexing not having finished yet. 1. **Confirm** your change was merged to the default branch in GitHub. 2. **Open** “Docs home,” then **use** the search bar to find the page and **open** it from results. 3. **Refresh** the page in your browser and **wait** a short time for indexing to complete if the content still appears older. 4. **Review** “Documentation opportunities” on “Docs home” to see if a suggested PR is listed for an update. If present, **preview** changes and **create PR** to update outdated docs in your GitHub repo. ## Search results don’t reflect recent changes You run a search on “Docs home” or inside a collection and results don’t match your latest edits. Hybrid vector search returns relevant pages quickly, but it relies on indexed content. 1. **Use** the exact terms from your recent commit or the page title to narrow results. 2. **Clear** the query and **retype** a non-empty search; empty queries return no results. 3. **Wait** a few minutes after large edits; results update once indexing completes. 4. **Provide** feedback on a result using thumbs up/down with tags and an optional comment to improve results over time. ## Drift findings feel noisy or low value Your “Documentation opportunities” list shows many drift findings, and it’s hard to focus on what matters. You can mute, dismiss, or skip items to keep your queue actionable. 1. **Open** “Docs home” and **search** or **browse** to the “Documentation opportunities” section. 2. **Review** each finding’s type and severity to decide whether it needs action now. 3. **Dismiss** findings that are not issues so they leave your active list. 4. **Mute** findings you don’t want to review for a period so they stop surfacing while you focus elsewhere. 5. **Skip** low-priority items for now and **focus** on higher-severity findings. 6. **Preview** suggested changes, then **create PR** for items that need updates in your GitHub repo. - Use favorites on collections you work on most so high-signal areas are easy to reach. - Hiding low-relevance collections reduces visual noise on “Docs home.” ## Suggested or open PRs don’t match what you expect You see suggested or open PRs in “Documentation opportunities,” but they don’t reflect your preferred change or target file. 1. **Open** the suggested or open PR from the list to **preview** the diff. 2. **Verify** the changes match your intent. If not, **dismiss** the finding to remove it from the queue. 3. **Edit** your docs directly in GitHub if a different update is needed; once merged, **wait** for indexing and recheck the list. ## Still need help - Recheck that you’re on “Docs home,” using a non-empty search query, and that your GitHub changes are merged to the branch Moxie Docs indexes. - If pages or findings remain incorrect after waiting for indexing, contact your workspace admin to confirm the repository connection and access. - If the issue persists, reach out to Moxie Docs support with the page URL, your search query, and a brief description of the mismatch. --- ## Article: Publish knowledge base URL: https://docs.moxiedocs.app/documentation/feature_overview/publish-knowledge-base Section: documentation ## Overview Use the Knowledgebase onboarding wizard (Beta) to turn your docs repository into a public knowledge base on a hosted subdomain, such as "acme.moxiedocs.app." The wizard walks you through naming the site, choosing the source repo and folders, reserving a subdomain, setting visibility defaults, and adding basic branding. When you finish, Moxie Docs writes a knowledge base configuration and publishes a hosted site on a dedicated apex. ## When to use it - You want a public home for support and product docs backed by your GitHub repo. - You need a quick way to reserve a hosted subdomain and apply consistent branding. - You want default visibility rules for what content appears publicly. - You prefer a guided setup that produces a working site immediately. ## How to use it 1. **Open the wizard.** From the Docs dashboard, start the Knowledgebase onboarding wizard (Beta). 2. **Enter a knowledge base name.** Provide a clear, reader-facing name for your site. This appears on the hosted site and in the dashboard. 3. **Select the source repository.** Choose the GitHub repo that Moxie Docs already connects to for your documentation. 4. **Choose the folder structure.** Pick the folders in your repo that contain the docs you want to publish. Confirm the structure matches how you want content organized on the site. 5. **Reserve a subdomain.** Enter the subdomain you want (for example, your company or project name). The wizard shows a live preview like "acme.moxiedocs.app" so you can confirm availability and spelling. 6. **Set visibility defaults.** Choose the default behavior for new and existing docs (for example, whether selected folders or categories are public by default). You can adjust item-level visibility later in the dashboard. 7. **Add branding.** Provide branding basics such as site name and accent choices so readers recognize your organization. The preview updates to reflect your selections. 8. **Review and confirm.** Check the summary of your name, source repo, folder structure, subdomain, visibility defaults, and branding. Make any needed edits before continuing. 9. **Publish.** Complete the wizard to write the knowledge base configuration and publish your hosted site on the reserved subdomain. You’ll see a confirmation with a link to visit your public knowledge base. 10. **Verify and share.** Open the subdomain link, spot-check a few pages for structure and visibility, then share the URL with your team and customers. ## Options and settings - Knowledge base name: Controls the reader-facing title shown on your hosted site. - Source repository: Sets which GitHub repo supplies content for the site. - Folder structure: Determines which folders are included and how content is organized. - Subdomain reservation: Reserves and assigns a hosted address like "yourname.moxiedocs.app." - Visibility defaults: Establishes what content is public by default; you can refine item-level visibility later. - Branding: Basic visual details so your public site reflects your organization. ## Tips - Check your folder selections carefully; the site navigation mirrors your chosen structure. - If a page doesn’t appear publicly, review the visibility defaults and the item’s visibility in the dashboard. - Keep the name and branding consistent with your other customer-facing sites to help readers trust the content. --- ## Article: Q&A answers seem wrong or outdated URL: https://docs.moxiedocs.app/guides/troubleshooting/qa-answers-seem-wrong-or-outdated Section: guides Overview If the Docs → Ask panel gives an answer that feels wrong, missing details, or outdated, you can quickly improve results. Use three tools: - Refresh indexing so Moxie Docs sees the latest docs - Add context with search and links in your question - Send feedback with tags to teach the system what went wrong Before you start - Make sure the docs you expect to see are already merged into your GitHub repository. Moxie Docs indexes what’s in the repo. 1) Refresh indexing to pull in recent doc changes If answers mention old behavior, start by refreshing indexing so the Q&A panel uses the latest docs. 1. Open Moxie Docs and go to the Docs workspace. 2. In the left navigation, open Docs → Ask. 3. At the top of the Ask panel, select Refresh or Reindex (if you see the refresh control). If you don’t see a refresh control, wait a few minutes after your repo changes merge; Moxie Docs updates indexing on its own. 4. Ask your question again. Tip: If your team recently merged large documentation updates, give indexing a short window to complete before retrying. 2) Add context to your question for better answers Clear, specific questions lead to better results, especially in big repositories. 1. In Docs → Ask, enter a focused question. Example: “How do we authenticate the CLI in v2?” instead of “How does auth work?” 2. Include names of relevant components, file or page titles, or version labels that appear in your docs. 3. Use the Docs workspace search bar to find the most relevant doc pages. Skim the results. 4. Copy a doc page title or link from search and paste it into your question to steer the answer toward the right material. 3) Use feedback tags to improve future answers Every answer has a feedback widget. 1. Under the answer, select thumbs up or thumbs down. 2. If you choose thumbs down, pick one or more tags: - Wrong: The content isn’t correct. - Missing context: The answer is too vague or skipped key details. - Outdated: The answer reflects old behavior or versions. 3. (Optional) Add a short comment that explains what should change. Examples: “We renamed this flag to --token,” or “Use v2 endpoints now.” 4. Submit. Your feedback helps Moxie Docs tune future answers and prioritize doc improvements. 4) When to use search instead of Q&A For quick lookups of a known topic, search can be faster. 1. Go to the Docs workspace. 2. Use the search bar to enter keywords, component names, or page titles. 3. Open the most relevant page to verify details, then return to Docs → Ask if you still need a synthesized answer. 5) If answers are still off after refreshing - Re-ask with added context and links from search results. - Confirm the correct information exists in your repo docs. If it doesn’t, update the docs in GitHub. After merge, refresh indexing and try again. FAQ - Will feedback change the current answer right away? Not always. Feedback improves future answers and helps your team keep docs accurate over time. - Do I need special permissions? You can use Docs → Ask, search, and feedback in the Docs workspace. Updating the source docs requires GitHub access in your repo. --- ## Article: Review drift cards and open focused doc PRs URL: https://docs.moxiedocs.app/documentation/feature_overview/review-drift-cards-and-open-focused-doc-prs Section: documentation Overview Use Moxie Docs to spot when your docs have fallen behind your code and quickly open focused pull requests (PRs) to fix them. You’ll review “PR opportunities” cards, open a proposed PR, and choose to apply, edit, dismiss, or mute findings. Admins can also turn specific detectors on or off per repository. What you’ll need - Access to your team’s Moxie Docs workspace - Your GitHub repository connected via the Moxie Docs GitHub App - Workspace admin role to dismiss/mute findings or change automation settings (owners/admins only) Understand drift and PR opportunities - Drift means your docs no longer match the code. Examples include stale or thin docs, undocumented APIs, orphaned pages, or convention mismatches. Cosmetic changes are suppressed. - Moxie Docs surfaces these as PR opportunities on the Docs dashboard. Each opportunity appears as a card with a short summary and actions. - When you open a PR from a card, Moxie Docs includes helpful guidance in the PR description and posts a single, deduplicated convention review comment on GitHub as findings change. Find and review drift cards 1) Go to Docs dashboard in your Moxie Docs workspace. 2) Scroll to the PR opportunities section. You’ll see cards grouped by repository. 3) Select a card to expand details. Review: - What changed or is missing - Suggested doc updates Moxie Docs can open as a PR - Repository name and any related notes Open a proposed PR from a card 1) On the card, select Open proposed PR. Moxie Docs creates a focused documentation PR in GitHub. 2) In GitHub, review the PR description. Moxie Docs aligns the description to your repo’s conventions. 3) Check the single “convention review” comment from Moxie Docs. It updates automatically if findings change, so you won’t get duplicates. 4) If everything looks good, proceed as you normally would: request review, make edits, and merge when ready. Apply or edit the suggested changes - Apply as-is: Merge the PR after your normal review. - Edit first: Use Edit on GitHub to adjust files or the PR description. Moxie Docs’s convention guidance stays in the same PR comment thread. Dismiss or mute a finding (admins) Use this when a card isn’t useful or should be hidden for a while. 1) On the card, open the overflow menu (· · ·). 2) Choose one of: - Dismiss: Hide this finding permanently. - Mute for 7 days: Hide until 7 days pass. - Mute for 30 days: Hide until 30 days pass. - Undo: Re-show a previously dismissed or muted finding. Notes - Only workspace owners/admins can dismiss or mute. - Dismissed or muted items disappear from PR opportunities until the mute window ends or you undo. Turn specific detectors on or off per repository (admins) 1) Go to Account in your Moxie Docs workspace. 2) Open the Repository automation tab. 3) In Detectors, use the checkboxes to enable or disable kinds of drift to flag for this repository (for example: stale docs, thin docs, undocumented APIs, orphaned pages, convention mismatches). Changes take effect for future findings. Tips - Start with high-signal cards: undocumented APIs and orphaned pages often deliver quick wins. - If you see repeated low-value signals, mute for 7 or 30 days and adjust detector checkboxes later. - Keep PRs focused. Smaller, targeted doc fixes are easier to review and merge. Troubleshooting - I don’t see PR opportunities: Confirm the repository is connected and you’re viewing the correct workspace. If you’re an admin, check detector settings on the Repository automation tab. - I can’t dismiss or mute: Ask a workspace owner/admin to adjust or grant the right role. - The PR shows multiple convention comments: Moxie Docs posts a single deduplicated comment. If you see more than one, refresh—earlier duplicates are consolidated as updates roll in. What happens in GitHub - PR description alignment: Moxie Docs guides authors to follow your repo’s description conventions. - Convention review comment: A single comment updates as findings change, reducing noise while you iterate on the PR. --- ## Article: Set up your public knowledgebase URL: https://docs.moxiedocs.app/documentation/getting_started/set-up-your-public-knowledgebase Section: documentation This guide walks you through turning a connected repository into a public help center on `your-team.moxiedocs.app`. Nothing reaches GitHub or the public web until you approve it. ## What you’ll need - A Moxie Docs workspace with GitHub connected and at least one repository indexed - Beta access to **Public Knowledgebase** (request access from Dashboard → Public Knowledgebase if you don’t have it yet) - Permission to open pull requests on the repo where docs will land ## How the flow works 1. **Generate** — Moxie Docs drafts help-center pages from your codebase (privately in Moxie Docs). 2. **Approve** — You review drafts in the inbox. Approval does **not** publish them. 3. **Open PRs** — Approved pages become pull requests of Markdown files in your target repo. 4. **Merge** — After merge, Moxie Docs indexes the files into the public site cache. 5. **Publish** — You toggle pages live on `{subdomain}.moxiedocs.app`. Approve and publish are independent gates. A page can sit merged-but-unpublished forever. ## Step 1: Get beta access 1. Open **Dashboard → Public Knowledgebase**. 2. If you see a **Request access** panel, submit a request and wait for approval. 3. When access is granted, Moxie Docs routes you into setup (or your existing review inbox). Tip: Workspace admins may need a Moxie Docs team member to grant the `public_knowledgebase` flag if you are in a private beta cohort. ## Step 2: Run the setup wizard 1. Open **Dashboard → Public Knowledgebase → Setup** (or follow the redirect after access is granted). 2. **Name & subdomain** — Pick a globally unique subdomain. Your site will be `https://{subdomain}.moxiedocs.app`. Custom domains are not available in beta. 3. **Target repo** — Choose where approved Markdown lands (same repo or another connected repo). Generation always uses your **active** repository as the source of product context. 4. **Docs folder** — Path inside the target repo (default is often `knowledgebase`). Moxie Docs creates it if needed. 5. **Audience** — Developer, end user, or both. This shapes tone and which page types get planned. 6. **Review & launch** — Confirm choices and start the first draft generation job. You land in the **Review** inbox while drafts generate. Refresh if the list is still empty after a few minutes. ## Step 3: Review and approve drafts 1. Open **Dashboard → Public Knowledgebase → Review**. 2. Expand a draft, read the Markdown preview, then **Approve** or **Dismiss**. 3. Use section batch actions when a whole group looks good. 4. Drafts marked **Needs review — source files changed** are stale updates; regenerate or dismiss them before publishing older content. Optional: open a draft **Preview** to read it full-width before approving. ## Step 4: Open PRs and merge 1. When at least one draft is approved, click **Open PRs**. 2. Moxie Docs groups approved pages and opens pull request(s) on the target repository. 3. Review the PR on GitHub like any docs change, then **merge**. Merged files become the durable copy in git. Moxie Docs syncs them into the public site cache (including a fast path on push for knowledgebase paths). ## Step 5: Publish pages on the hosted site 1. In the Review inbox, open the **Published** tab (or the list of pages ready to go live). 2. Toggle **Publish** on pages you want on the public site. 3. Open `https://{subdomain}.moxiedocs.app` and confirm the page appears. Unpublish anytime from the same controls. Unpublished pages stay in git; they just do not render on the hosted site. ## Step 6: Branding (optional) 1. Open **Dashboard → Public Knowledgebase → Settings**. 2. Set: - **Title** — help center name in the header - **Logo URL** — optional `https://` image - **Accent color** — optional hex (e.g. `#0ea5e9`) for the header accent and active nav 3. Save and hard-refresh the public site. ## Keeping docs current - **Regenerate** — Queues a new generation pass grounded in the latest product model and feedback. - **Stale updates** — Appear when source files used for a draft change after generation. - **Article feedback** on the public site — Feeds future generation when readers report issues. - **Edit** — Use the edit link on a published page to open Moxie Docs’s repo doc editor for that Markdown file. ## Troubleshooting | Symptom | What to try | | --- | --- | | No access to setup | Request access; confirm a teammate granted the public knowledgebase beta flag. | | Empty review inbox after launch | Wait for the generation job; check indexing/jobs for `kb_generate` failures. | | PR open fails | Confirm GitHub App access to the **target** repo and that the org can open PRs. | | Site shows empty shell | Pages must be **published** after merge—not only approved. | | Branding not showing | Logo must be HTTPS; accent must be `#RGB` or `#RRGGBB`. Hard-refresh the public URL. | | Wrong kind of docs (internals) | Prefer product-facing README/marketing/UI signals; dismiss bad drafts and regenerate. | ## What beta does not include yet - Custom domains (e.g. `docs.yourcompany.com`) - Full white-label (removing the Moxie Docs footer) - Enterprise KB-only RBAC Those ship after the subdomain beta is stable. --- ## Article: Set your collection preferences URL: https://docs.moxiedocs.app/documentation/feature_overview/set-your-collection-preferences Section: documentation ## Overview Collections group your docs into clear themes like "Get started," "Understand the architecture," and "Operate & deploy" on Docs Home. You can choose favorites and set the order of collections so the most important content appears first. This helps new teammates onboard faster and makes daily navigation quicker for everyone. ## When to use it - You want "Get started" and onboarding content front and center for new hires. - You frequently open the same collections and want them at the top. - You need a consistent order for team walkthroughs or training. - You’re streamlining Docs Home to match how your team works. ## How to use it 1. **Open** Docs Home from your Moxie Docs dashboard. 2. **Review** the collections grid to see the available collections (for example, "Get started," "Understand the architecture," "Operate & deploy"). 3. **Choose favorites** by marking the collections you visit most often so they’re highlighted for quick access. If you don’t see a star or favorite control, continue to the next step and rely on ordering instead. 4. **Set the order** of collections so the most important ones appear first on Docs Home. Move the collections into your preferred sequence. 5. **Confirm** your changes and return to Docs Home to make sure your favorites and order look right. 6. **Use** your personalized layout during onboarding and daily work. Adjust favorites or order anytime as your needs change. ## Options and settings - Collections: The groups shown on Docs Home, such as "Get started," "Understand the architecture," and "Operate & deploy." - Favorites: A way to mark collections you want quick access to. - Order: The sequence collections appear in on Docs Home. ## Tips - Keep "Get started" first to speed up new teammate onboarding. - Limit favorites to the collections you open daily so the grid stays focused. - Revisit your order after major documentation changes to keep navigation efficient. --- ## Article: Share changelog to Slack URL: https://docs.moxiedocs.app/guides/integration_guide/share-changelog-to-slack Section: guides ## Overview Connect Slack to Moxie Docs so your team sees what changed in your docs without leaving chat. After setup, Moxie Docs will post weekly recaps of documentation updates and announce new doc pull requests created from drift findings to a Slack channel when they’re available. ## Before you start - A Moxie Docs account with access to the dashboard - Your GitHub repository already connected to Moxie Docs - A Slack workspace where you can approve apps and post to a channel - Permission to choose or create a channel for updates ## Connect 1. **Open** the Moxie Docs dashboard and **go to** the area where you manage integrations or chat connections. If you do not see Slack, **open** your account or workspace settings and **look for** integrations. 2. **Select** Slack and **start** the connection. This opens Slack’s authorization screen in your browser. 3. In Slack, **review** the requested permissions and **choose** the Slack workspace. 4. **Click** Allow to approve the connection and return to Moxie Docs. 5. Back in Moxie Docs, **confirm** the Slack channel you want to use for updates. If prompted, **pick** a public or private channel you have access to. Note: If your Slack admin requires approval, Slack may route the request to an admin before the connection completes. ## Configure After connecting, set where and what Moxie Docs should post: - Channel: Select the Slack channel that should receive updates. - Weekly recap: Enable posting a weekly summary of documentation changes when a recap is available. - New doc pull requests: Enable posting an announcement when Moxie Docs creates a PR to update outdated docs. - Repository scope: If you manage multiple repos in Moxie Docs, choose which connected repositories should send updates to Slack. ## Verify it works - Post test: In the Slack configuration area, send a test message and confirm it appears in the selected channel. - Weekly recap check: After the next weekly cycle, confirm a recap message appears in the channel when there are changes to share. - PR announcement check: Create or approve a doc PR from a drift finding in Moxie Docs and confirm an announcement posts in the channel. - Connection status: In the Moxie Docs Slack settings, confirm the connection shows as connected to the correct workspace and channel. ## Disconnect or change access - To change the channel or what gets posted, **open** the Slack settings in Moxie Docs and **update** the channel and options. - To remove Slack from Moxie Docs, **open** the Slack connection in Moxie Docs and **disconnect** it. Then, in Slack, **open** the workspace app management page and **remove** the Moxie Docs app if you no longer want it available. - If your Slack workspace or channel permissions change, **reconnect** Slack from Moxie Docs to refresh access. --- ## Article: Stripe billing setup and syncing URL: https://docs.moxiedocs.app/guides/integration_guide/stripe-billing-setup-and-syncing Section: guides This page shows you how to start a Moxie Docs subscription with Stripe Checkout, manage it in the Stripe Customer Portal, and understand how plan changes affect your workspace and connected repositories. ## What you’ll need - A Moxie Docs workspace - Permission to manage billing for your workspace ## Start a subscription with Stripe Checkout 1. **Open** your Moxie Docs workspace. 2. **Click** your profile menu and select **Workspace settings**. 3. **Go to** the **Billing** tab. 4. **Click** **Choose a plan** to open Stripe Checkout. 5. **Select** your plan and any available trial, then **enter** your payment details. 6. **Confirm** the purchase. You’ll be returned to Moxie Docs. After checkout, your workspace shows the active plan and renewal date on the **Billing** tab. ## Manage your subscription in the Customer Portal Use the Stripe Customer Portal to update payment methods, change plans, or cancel. 1. **Open** your workspace **Billing** tab in Moxie Docs. 2. **Click** **Manage in Stripe**. This opens the Stripe Customer Portal. 3. In the portal, you can: - **Update** payment methods and billing details - **Change** plans - **View** invoices and receipts - **Cancel** your subscription 4. **Save** your changes and **return** to Moxie Docs. Your workspace billing status updates automatically after you make changes in the portal. ## How plan changes sync to your workspace and repositories Moxie Docs keeps your billing status in sync and applies plan limits to your workspace and connected repositories. - When you start a trial or activate a paid plan, features and limits included in your plan become available across your workspace. - When you upgrade, higher limits (for example, more repositories or automation capacity) are unlocked for all connected repos in that workspace. - When you downgrade, limits adjust accordingly. If you’re over a new limit, Moxie Docs guides you to choose which repositories remain active. - If your subscription is canceled or a payment fails, affected features are paused according to your plan’s rules. You can restore access by updating payment and reactivating in the Customer Portal. - The **Billing** tab shows your current plan, trial status (if applicable), next charge date, and any limit usage so you can see what’s applied to each repository. ## Verify your subscription status 1. **Open** your workspace **Billing** tab in Moxie Docs. 2. **Check** the **Plan**, **Status** (Active, Trialing, Canceled), and **Next charge date**. 3. **Review** any limit indicators to see how they impact connected repositories. ## Troubleshooting - Changes not showing? **Refresh** the Billing tab after a few minutes. Billing status updates shortly after you finish in the Customer Portal. - Need to switch plans but you’re over a limit? **Adjust** active repositories when prompted, then **confirm** the change. - Payment issues? **Open** **Manage in Stripe** from the Billing tab to update your payment method or retry a payment. If you still need help, contact support from the **Help** menu in Moxie Docs with your workspace name and a brief description of the issue. --- ## Article: Troubleshoot GitHub App and repository access URL: https://docs.moxiedocs.app/guides/troubleshooting/troubleshoot-github-app-and-repository-access Section: guides ## Overview Use this guide to fix problems that stop Moxie Docs from connecting to GitHub, syncing repositories, or showing fresh documentation signals. It covers GitHub App install issues, missing or incomplete repository access, and situations where drift cards, PR opportunities, or documentation look stale. Follow the sections in order to verify install, permissions, sync status, and data availability in the Docs dashboard. ## Before you start - You can sign in to Moxie Docs and open the Docs dashboard for your workspace. - You know who your workspace owner or admin is (they can change workspace settings and manage automation). - You have access to the GitHub organization or repositories you expect to use with Moxie Docs. ## Repository does not appear in Moxie Docs You installed the GitHub App but a repository you expect to see is missing from the Docs dashboard. This usually means the app was installed for the wrong scope or the repo was not selected during install. 1. **Open** the Docs dashboard and confirm which repositories are shown. 2. **Check** the GitHub App installation to confirm the correct organization and repositories are selected. - If you manage the GitHub App, open your GitHub organization’s settings and review the app’s installation. - Make sure the app is installed on the organization that owns the missing repository. - Make sure the specific repository is selected if the app is limited to selected repositories. 3. **Refresh** Moxie Docs by reopening the Docs dashboard and waiting a few minutes for the list to update. 4. **Ask** a workspace owner or admin to verify that the repository is allowed in your workspace if it is intentionally filtered. ## Repositories show, but docs or code aren’t indexed You can see the repository in Moxie Docs but no drift cards appear, and PR suggestions look incomplete. This usually means Moxie Docs has not finished its first sync or indexing for that repo. 1. **Open** the Docs dashboard and go to the PR opportunities section. 2. **Confirm** whether any cards are grouped under the repository. If none show after first install, allow time for analysis to complete. 3. **Check** that the repository has recent commits. If there are no recent changes, drift cards may be limited until new code changes occur. 4. **Reopen** the Docs dashboard after a few minutes to see if cards start to appear. 5. **Ask** a workspace owner or admin to confirm that automation for that repository is enabled and not paused. ## Drift cards don’t appear where you expect them You expect to see drift findings (e.g., stale docs or undocumented APIs), but the PR opportunities section is empty or missing items. 1. **Open** the Docs dashboard and locate the PR opportunities section grouped by repository. 2. **Filter** visually by repository group and **check** if cards are hidden. - Workspace owners and admins can hide low‑value drift findings permanently or for a set time window and undo later. - If cards were hidden, **ask** an owner or admin to unhide them so they appear again. 3. **Confirm** which drift detectors are enabled for the repository. - **Ask** an owner or admin to review per‑repo automation controls and turn on the detectors you want to use. 4. **Reopen** the Docs dashboard to refresh the list of cards after changes. ## Docs look stale in the Docs dashboard Pages or summaries in the Docs dashboard don’t reflect recent code changes, or suggestions seem out of date. 1. **Reopen** the Docs dashboard to trigger a fresh view of current status. 2. **Verify** that recent pull requests affecting docs were merged in GitHub. 3. **Check** the PR opportunities section for new cards that highlight stale docs or convention mismatches. 4. **Open** a card to view details and, if appropriate, **open** a focused docs pull request to update the content. 5. **Confirm** that the consolidated guidance comment on related GitHub pull requests has the latest alignment guidance. ## Pull request suggestions seem incomplete Moxie Docs creates focused documentation pull requests with suggested updates and a single deduplicated “convention review” comment. If suggestions seem incomplete, the repository’s automation or detectors may be limited, or the PR description is out of alignment. 1. **Open** the relevant card in the PR opportunities section and **review** the suggested changes. 2. **Open** the GitHub pull request created from the card and **read** the consolidated, auto‑updating guidance comment. 3. **Align** the PR description with the guidance so Moxie Docs can refine its suggestions. 4. **Ask** a workspace owner or admin to adjust per‑repo automation, including which drift detectors are enabled and whether recap comments on PRs are turned on. 5. **Recheck** the card in the Docs dashboard after a few minutes for updated suggestions. ## GitHub App is installed, but access errors persist You installed the GitHub App, but Moxie Docs still can’t access repositories or data. This often comes from permission mismatches or installing the app on personal scope instead of the organization. 1. **Confirm** the app is installed on the correct GitHub organization that owns the target repositories. 2. **Verify** the installation includes all required repositories. - If the app is set to selected repositories, **add** the missing repositories to the installation. 3. **Sign out and sign back in** to Moxie Docs to refresh your session, then **open** the Docs dashboard again. 4. **Ask** a workspace owner or admin to confirm your user has access to the workspace and to the repositories shown in the Docs dashboard. ## Cards appear, but you cannot open a focused docs PR You see drift cards but can’t create the pull request from Moxie Docs. 1. **Open** the card in the PR opportunities section and **review** the options presented. 2. **Check** that you have permission in GitHub to open pull requests in that repository. 3. **Ask** a workspace owner or admin to confirm per‑repo automation allows creating pull requests from Moxie Docs. 4. **Retry** opening the focused docs pull request from the card. ## Changes were hidden and now you need them back Findings were hidden earlier and now the dashboard looks empty for a repository. 1. **Ask** a workspace owner or admin to **undo** hidden drift findings for the repository. 2. **Reopen** the Docs dashboard and **confirm** the PR opportunities section now shows the restored cards. ## End‑to‑end sanity check If multiple steps above did not help, confirm the full flow from install to data in Moxie Docs. 1. **Verify** the GitHub App is installed on the correct organization and includes the right repositories. 2. **Confirm** you can see the repository group in the PR opportunities section in the Docs dashboard. 3. **Check** for at least one recent commit or open pull request touching docs or code that affects docs. 4. **Look** for cards appearing after analysis completes. If present, **open** one and **create** a focused docs pull request. 5. **Review** the consolidated guidance comment on the GitHub pull request and **align** the description as suggested. 6. **Return** to the Docs dashboard and **confirm** status updates appear after a short delay. ## Still need help - Recheck that the GitHub App is installed on the correct organization and that the needed repositories are selected. - Confirm a workspace owner or admin has enabled the right drift detectors and has not hidden current findings. - If problems persist, contact your workspace owner or admin and share what you verified above, including the repository name, the organization, and a link to any related GitHub pull request. --- ## Article: Troubleshoot GitHub connection and indexing URL: https://docs.moxiedocs.app/guides/troubleshooting/troubleshoot-github-connection-and-indexing Section: guides ## Overview This guide helps you fix problems connecting GitHub to Moxie Docs, granting repository access, and getting the first index to run so docs show up in your dashboard. Use it when a repository is missing, the GitHub App was installed but nothing appears, or the index is stuck or not finishing. ## Before you start - You have access to your Moxie Docs workspace and can open the dashboard. - You are a manager in Moxie Docs if you need to activate repositories. Members can view status but may be directed to repository settings. - You can sign in to GitHub and, if needed, have permission to install or update the GitHub App on the right repositories. ## Repository does not appear in Moxie Docs You installed the GitHub App or expected to see a repository, but it does not show up in your Moxie Docs dashboard. 1. **Confirm** you are signed in to the correct GitHub account that owns the repository. 2. **Check** that the GitHub App was installed on the organization that hosts the repository. - If you lack permission to manage apps in GitHub, **ask** an organization owner to review the installation and repository access. 3. **Refresh** the Moxie Docs dashboard and **look** for your repository again. If you are a member, you may see a link to repository settings when activation is required. 4. **Verify** that the repository was granted access during the GitHub App install. If only “All repositories” or a different subset was selected, **update** the GitHub App settings in GitHub to include the missing repository. ## “Activate Repo” button is disabled or missing You see the repository in Moxie Docs, but you can’t turn on Docs for it. The “Activate Repo” button may be disabled, or you only see a link to settings. 1. **Confirm** your Moxie Docs role. Only managers can activate a connected repository. 2. If you are a member, **click** the link to repository settings shown in the first‑index view to notify a manager or request activation. 3. Managers: **Open** the repository in Moxie Docs and **click** “Activate Repo” under the Status header in the first‑index view. - If activation is blocked, **check** that the workspace has an active plan that allows Docs for this repository and that the GitHub App still has access. ## First index never started You activated the repository, but no docs were created and no job appears to be running. 1. **Open** the repository’s first‑index view and **check** the Status header. 2. **Click** “Activate & Queue” to queue the first indexing job. 3. If a job is already queued but hasn’t begun, **wait** a moment. The page auto‑refreshes while work is queued. 4. If the queue appears idle after refresh, **click** “Run queued job once” to start the job. 5. If controls are disabled, **confirm** you are a manager and the repository remains connected in GitHub. ## Index is stuck in queued or running You can see a queued or running job, but it never seems to finish and the page keeps auto‑refreshing with no progress. 1. **Stay** on the first‑index view and **watch** for auto‑refresh updates for a few minutes. 2. **Cancel** and **re‑queue** the job if a cancel option is shown, then **click** “Activate & Queue” again. 3. **Run** the queued job by clicking “Run queued job once.” 4. **Recheck** GitHub App access for the repository. If access was removed, **restore** it in GitHub and then **re‑queue** the job. ## Docs did not appear after a completed run The first index appeared to complete, but you do not see any generated docs in the dashboard collections. 1. **Refresh** the repository page and **browse** your collections or **search** across generated pages. 2. **Verify** you activated the correct repository and that it contains code or docs to index. 3. **Queue** another run by clicking “Activate & Queue,” then **run** it once with “Run queued job once.” 4. If you’re a member and cannot retry, **contact** a manager to review the first‑index status. ## I don’t have permission to proceed You are blocked by permissions in Moxie Docs or GitHub when trying to activate a repo or start the index. 1. **Check** your Moxie Docs role in the workspace. Members may be directed to repository settings and cannot activate or run jobs. 2. **Ask** a Moxie Docs workspace manager to activate the repository or run the job from the first‑index view. 3. **Request** GitHub organization owner help to install the GitHub App or grant the repository access if you cannot change it. ## Still need help - **Recheck**: your Moxie Docs role (manager vs. member), GitHub App installation on the correct organization, and that the specific repository is granted access. - **Contact** your Moxie Docs workspace admin or manager if you need activation or job controls. - If the issue persists after these steps, **capture** the repository name and what you see under the Status header and **share** it with your workspace admin for review. --- ## Article: Troubleshoot GitHub PRs URL: https://docs.moxiedocs.app/guides/troubleshooting/troubleshoot-github-prs Section: guides ## Overview This guide helps you resolve problems when Moxie Docs cannot create or update a pull request in your GitHub repository. It covers common blockers such as missing access, protected branches, failing checks, and repositories that do not appear. ## Before you start - You can sign in to your Moxie Docs workspace. - Your GitHub account is linked to the workspace with access to the target repository. - You have write access on GitHub to open pull requests in the repository you want to update. - You know which repository and branch Moxie Docs should propose changes to. ## Repository does not appear in Moxie Docs You try to create a PR from Moxie Docs but the expected repository is missing in selection or search. 1. **Confirm** you are signed in to the correct Moxie Docs workspace that is connected to the right GitHub account. 2. **Verify** your GitHub account has access to the repository. Ask a repository owner to add you or your team if needed. 3. **Refresh** the repository list in Moxie Docs by reopening the PR creation flow, then search again by the exact repository name. 4. **Check** that the repository still exists and has not been archived or moved in GitHub. - If you recently gained access on GitHub, wait a few minutes and try again so Moxie Docs can see the change. ## You do not have permission to open a PR You see an error about insufficient permissions when Moxie Docs tries to open or update a pull request. 1. **Ask** a repository admin to grant your GitHub user write access on the repository. 2. **Request** approval for any organization-level policy that limits third‑party app actions if your company uses them. 3. **Retry** the PR creation in Moxie Docs after access is granted. - If access is intentionally restricted, share the proposed changes with a teammate who has permission and ask them to create the PR. ## Branch is protected and PR cannot target it Your default branch is protected on GitHub, and Moxie Docs cannot push changes directly or select it as an editable target. 1. **Create** a new feature branch name during PR creation in Moxie Docs if prompted, rather than targeting the protected branch directly. 2. **Ensure** you have permission to push branches to the repository. Ask a repository admin if branch creation is restricted. 3. **Open** the pull request from the feature branch into the protected branch, then follow your repository’s required review process in GitHub. - Protected branch rules still apply after the PR is opened. Reviews and checks must pass before merging. ## Required checks are failing on the PR The pull request is created, but status checks (like CI, tests, or required reviews) fail and the PR cannot be merged. 1. **Open** the pull request in GitHub and review the “Checks” and “Conversation” tabs for failure details. 2. **Resolve** the reported issues in the repository (for example, update documentation content, fix link validations, or address formatting rules) using your normal contribution process. 3. **Re-run** the checks from GitHub if available, or push a small update from Moxie Docs by creating an updated PR commit. - If your repository requires specific approvals, request reviews from the correct code owners or reviewers in GitHub. ## PR was created but you cannot find it Moxie Docs reported a successful PR, but you do not see it in GitHub or in your workspace. 1. **Search** for open and closed pull requests in the target repository by your username and today’s date. 2. **Check** if the PR was opened against a fork or a different branch than expected. Review the base and compare branches on the PR list. 3. **Retry** creating the PR from Moxie Docs, making sure you select the correct repository and base branch. - Ask a teammate with repository admin access to confirm PR visibility if organization policies limit your view. ## Updates to an existing PR are not appearing You add new changes from Moxie Docs, but the existing PR does not update or shows outdated content. 1. **Confirm** you selected the same repository and branch as the open PR’s source branch when sending updates. 2. **Wait** a few minutes for GitHub to show the new commit on the PR, then refresh the PR page in GitHub. 3. **Create** a new PR if the original branch is locked or cannot accept new commits due to repository rules. - If required checks are stuck in a pending state, re-open the PR page in GitHub and re-run checks if that control is available to you. ## Organization policies block third‑party changes Your company’s GitHub organization restricts actions by connected apps, which can prevent Moxie Docs from creating PRs. 1. **Ask** an organization owner to review app access policies and confirm that changes from your workspace are allowed for the target repository. 2. **Validate** that your GitHub user and the repository are included in any required allowlists. 3. **Retry** the PR creation in Moxie Docs after the policy is updated. - If policies cannot be changed, coordinate with a repository maintainer to create the PR based on the proposed changes. ## Still need help - Recheck your repository access, the target branch, and any required checks in GitHub. - If issues continue, contact your workspace admin to review permissions and connected accounts. - Share the exact repository name, branch, and the time you attempted the PR to speed up troubleshooting. --- ## Article: Troubleshoot indexing URL: https://docs.moxiedocs.app/guides/troubleshooting/troubleshoot-indexing Section: guides ## Overview This guide helps you fix common issues that stop documentation from generating in Moxie Docs. Use it if pages are missing, an indexing job seems stuck, or you see permission or subscription errors. Work through the sections that match what you’re seeing. ## Before you start - You can sign in to the Marketing site using Sign in with GitHub. - You have access to your workspace Dashboard. - Your GitHub account can install apps on the target repository, or you can ask a repository admin to do it. - You can view Billing/Subscription in the Dashboard, or ask a workspace admin to check it. ## Repository does not appear in Moxie Docs You’ve signed in but can’t find the repository you want to connect. This usually means the GitHub App isn’t installed for that repo or the account you used doesn’t have access. 1. **Sign in** to the Marketing site and choose Sign in with GitHub. 2. **Open** the Dashboard and follow the first‑run prompts to select/install the GitHub App. - Choose the GitHub organization and repositories you want Moxie Docs to access. - If you don’t see the organization, switch accounts in GitHub or ask an org admin to grant access. 3. **Refresh** the Dashboard and **select** the repository. If it still doesn’t appear, confirm you have read access to the repo in GitHub. ## Indexing never starts You clicked into a repository but no pages generate and no job appears to run. This can happen if your trial or subscription isn’t active. 1. **Open** Dashboard → Billing/Subscription. 2. **Start** your 14‑day trial or **complete** checkout to begin a paid plan in Stripe Checkout. 3. **Wait** a moment for the status to update; webhooks keep your subscription in sync. Then **return** to the repository and **start** indexing again from Docs. ## Indexing is stuck or very slow A job shows as running for a long time and pages don’t update. Network delays or a transient GitHub issue may pause progress. 1. **Wait** a few minutes, then **refresh** the Docs page for the repository. 2. **Retry** the indexing job from the Docs view if available. 3. **Confirm** your subscription is active in Billing/Subscription. If inactive, **restore** it and then **retry** indexing. ## Permission error when connecting GitHub You see a message that Moxie Docs can’t read the repository or open docs‑only PRs. This means the GitHub App doesn’t have permission on that repo. 1. **Open** the Dashboard and **select** the repository flow again to manage the GitHub App. 2. **Update** the installation to include the specific repository, or **switch** to an account with admin rights to install the app. 3. **Return** to the Docs page and **start** indexing again. ## Pages are missing after indexing Indexing completes, but expected topics don’t show up in the Docs collections or search. 1. **Refresh** the Docs page and **browse** the collections (for example, Get started, Architecture, Backend) to verify where pages landed. 2. **Run** indexing again from the Docs view to pick up recent changes. 3. **Check** with a teammate that the source content exists in the connected repository branch you intended to index. ## Search shows outdated content You find a page, but the information looks old. The repo may have changed since the last indexing run. 1. **Open** the Docs page for the repository. 2. **Trigger** a new indexing job to regenerate pages. 3. **Verify** the page shows updated content and is searchable again. ## Docs-only PRs are not appearing in GitHub You expect a docs‑only PR but nothing shows up. This can be caused by missing app permissions or an inactive subscription. 1. **Confirm** in Dashboard → Billing/Subscription that your trial or plan is active. 2. **Revisit** the GitHub App installation from the Dashboard first‑run flow and **include** the target repository. 3. **Retry** indexing from the Docs page and then **check** the repository’s Pull Requests in GitHub. ## Still need help - Recheck: you are signed in with the correct GitHub account, the GitHub App is installed for the exact repository, and your subscription in Billing/Subscription is active. - If problems continue, contact your workspace admin to confirm permissions or to adjust the GitHub App installation. If your admin can’t resolve it, share screenshots of the Dashboard and any error messages when you contact support. --- ## Article: Tune repository automation settings URL: https://docs.moxiedocs.app/documentation/feature_overview/tune-repository-automation-settings Section: documentation ## Overview Use repository automation to keep docs in step with code. Moxie Docs shows opportunity cards when documentation falls behind, and lets you open focused doc pull requests (PRs) right from the dashboard. You can also dismiss or mute individual findings to reduce noise, and admins can enable or disable specific detectors per repository to shape what appears. ## When to use it - You see drift between code changes and docs and want quick, focused updates. - Your team needs fewer noisy alerts and more relevant suggestions. - You want to review and merge proposed doc PRs from one place. - You need to temporarily silence a finding while work is in progress. ## How to use it 1. **Open** the Docs dashboard and go to the repository you want to review. 2. **Review** opportunity cards that flag where docs may have fallen behind code. 3. **Open** a focused doc PR from a card to see the proposed changes in GitHub. 4. **Review and edit** the proposed PR as needed, then **merge** it in GitHub when ready. 5. If a card is not useful, **click** its overflow menu and **choose** Dismiss to remove it. 6. To reduce short-term noise, **click** the overflow menu and **choose** Mute 7d or Mute 30d to pause that finding for the selected period. 7. If you are an admin and want to change what gets flagged, **open** repository automation settings and **adjust** Detectors for that repository by enabling or disabling specific detectors. 8. **Return** to the dashboard to confirm that only relevant opportunity cards appear going forward. ### Admin: tune detectors per repository 1. **Open** account settings and go to the repository’s automation controls. 2. **Select** the Repository automation tab. 3. **Open** Detectors and **enable or disable** the specific detectors you want active for this repository. 4. **Save** your changes and **refresh** the Docs dashboard to see updated opportunity cards over time. ## Options and settings - Overflow menu on opportunity cards: Dismiss, Mute 7d, Mute 30d. - Detectors (per repository, admin only): Enable or disable individual drift detectors to shape which opportunity cards appear. ## Tips - Use Dismiss when a finding is not relevant; use Mute when it is valid but not actionable yet. - Start with a smaller set of detectors and add more once your team is comfortable with the volume. - After merging a focused doc PR, give the system a moment to update and clear the corresponding card. - Detector changes affect future cards; existing muted or dismissed items keep their current state. --- ## Article: Use code previews and search helpers URL: https://docs.moxiedocs.app/documentation/feature_overview/use-code-previews-and-search-helpers Section: documentation Overview Use the Code dive and Code search helpers in your Moxie Docs workspace to quickly preview repository files and scan for related code while you read docs, answer questions, or review changes. These helpers open side panels with file previews or search results so you can inspect paths, languages, and snippets without leaving the page. Before you start - You need access to a repository connected to Moxie Docs via the GitHub App. - Open your Moxie Docs workspace in the browser. Open a file preview with Code dive Use this when you already know the file or path you want to inspect. 1) In your workspace, look for the panel or link labeled Code dive. You’ll see it alongside docs tools such as Search, Q&A, or Changelog. 2) Select Code dive to open the panel. 3) Browse or paste a repository path to a file. The panel shows: - File path - Detected language (based on the file extension) - File content preview (long files are truncated so they load quickly) 4) Scroll the preview to skim the content. When you’re done, select Close to return to your doc view. Tips - If a file is very large, you’ll see only the beginning of the file. Use this to confirm you’re in the right place before opening it in GitHub. - Language is inferred automatically, so syntax highlighting reflects the file type. Search the codebase with Code search Use this when you don’t know the exact file but want to find references or examples. 1) In your workspace, select Code search. 2) Enter a term to find (for example, a function name, config key, or filename fragment). 3) Select Search. The results list shows matches with: - File path - Detected language - One or more text snippets around the match 4) Select a result to open its preview. You’ll see a truncated view so you can quickly confirm relevance. 5) To refine, adjust your search term and run Search again. Common workflows - From docs or Q&A answers: When a page references a file or symbol, open Code dive or Code search from the sidebar to verify details before you make any changes. - While reviewing drift or changelog items: Use Code search to find all related references, then open previews to confirm context. What you’ll see and what it means - Path: The location of the file in your repository. - Language: The file type inferred from the extension (for example, .ts, .md). - Snippet: A short section of text around the match to help you judge relevance quickly. - Truncated content: Large files are shortened in the preview to keep things fast. Open the file in GitHub if you need the full content. Troubleshooting - No results: Try a broader term or remove punctuation. If the repository was just connected, indexing may still be in progress—check again in a few minutes. - Preview won’t load: Refresh the page. If it persists, open the file directly in GitHub from the repository. Next steps - Use the previews to confirm you’ve found the right code, then proceed with your documentation task (for example, updating a page or submitting feedback on an answer). Your quick checks here help keep docs accurate without context switching. --- ## Article: Use Friday Recap and Cleanup URL: https://docs.moxiedocs.app/documentation/feature_overview/use-friday-recap-and-cleanup Section: documentation ## Overview Friday Recap gives you a simple weekly summary of what changed in your docs and what needs attention. When useful fixes are available, it proposes a Friday Cleanup pull request (PR) that bundles safe, docs‑only updates for easy review. It’s designed for teams who want to keep docs tidy without chasing every small change. ## When to use it - You want a quick, readable summary of weekly doc activity. - You need a single, reviewable PR that packages up multiple small fixes or deletions. - You prefer to decide if and when a Cleanup PR is opened, rather than auto‑merging changes. - You want to control who can see weekly recaps on the dashboard. ## How to use it 1. **Open** the Moxie Docs dashboard. 2. **Find** the Friday Recap card on the dashboard. It lists the week’s highlights and any proposed Cleanup PR. 3. **Review** the summary. Expand items to see suggested fixes, areas affected, and any orphaned pages flagged for deletion. 4. **Decide** what to do: - If the recap looks useful, **click** Open Friday Cleanup PR on the card to create a docs‑only GitHub PR. - If it’s not relevant this week, **click** Dismiss to remove the recap from your view. 5. **Confirm** the repository in the confirmation dialog. Moxie Docs respects your repository settings and will never auto‑merge. 6. **Switch to GitHub** when prompted and **review** the PR. The PR bundles related doc fixes to maximize value per slot. 7. **Request reviews** from teammates as usual, then **merge** in GitHub when ready. 8. Back in Moxie Docs, **check** the Opportunity or Suggestions area on the dashboard. The status will reconcile after the PR is opened and merged, so remaining suggestions stay accurate. ## Options and settings - Friday Recap card - **Open Friday Cleanup PR**: Creates a reviewable, docs‑only PR that groups related fixes and cleans up orphans when applicable. - **Dismiss**: Hides the recap for the week. Dismissed recaps don’t trigger a Cleanup PR. - Visibility - **Recap visibility** follows your dashboard access. Team members with dashboard access can see the Friday Recap card. - Automation behavior - **Docs‑only PRs**: Cleanup PRs never include code changes and never auto‑merge. - **Repository settings respected**: The PR uses your repo’s default branch and PR templates if configured. - **Bundling by area**: Related fixes are packaged together to reduce review overhead. ## Tips - Skim the recap first; if the value is low this week, dismiss it and revisit next Friday. - Use PR templates to guide reviewers on what changed and how to verify. Moxie Docs will apply your template if set up. - After merging, refresh the dashboard to see updated suggestion statuses and fewer repeat alerts. - If recaps feel noisy, tune detectors or mute specific drift alerts in the dashboard to improve future recommendations. --- ## Article: Workspace onboarding and invitations URL: https://docs.moxiedocs.app/documentation/feature_overview/workspace-onboarding-and-invitations Section: documentation ## Overview Use workspace onboarding to bring your team into Moxie Docs so everyone can work from the Docs dashboard. You’ll sign in with GitHub, connect the repositories you want Moxie Docs to index, invite teammates, and help them accept. Once everyone is in, the team can see Q&A, review the changelog from pull requests, get Friday Recaps, and manage per‑repo automation from the shared dashboard. ## When to use it - You’re setting up Moxie Docs for your organization for the first time. - You need to add teammates so they can review docs and PR-driven changes. - You want everyone working from the same Docs dashboard across connected repos. - You’re ready to expand access as more repos are connected. ## How to use it 1. **Open** Moxie Docs in your browser. 2. **Start GitHub sign‑in** by going to “Sign in with GitHub.” This begins GitHub OAuth and preserves a safe redirect back to your Docs dashboard. 3. **Authorize** on GitHub when prompted. Follow GitHub’s screens to grant access and, if needed, install the GitHub app for the repos you want to use. 4. **Return** to the Docs dashboard after GitHub redirects you back. You’ll land on the dashboard for your workspace. 5. **Connect** the GitHub repositories you want Moxie Docs to use. Select the repos you want indexed so the dashboard can show Q&A, the changelog from pull requests, and Friday Recaps. 6. **Invite** your teammates from the Docs dashboard. Use the invitation option you see on the dashboard to add the people who should collaborate in this workspace. 7. For each teammate: **Ask them to accept** the invitation in their email or on the Docs dashboard if they sign in directly. 8. Teammates should **Sign in with GitHub** using the same “Sign in with GitHub” button, then **Authorize** on GitHub if prompted. They’ll be redirected back to the Docs dashboard and added to the workspace once they accept. 9. As a team, **Review** the dashboard together: use Q&A for questions, check the changelog from pull requests, scan Friday Recaps, and adjust per‑repo automation controls as needed. ## Options and settings - GitHub sign‑in: Starts OAuth at “Sign in with GitHub,” redirects to GitHub, then returns you to the Docs dashboard with a safe post‑auth redirect. - Repository selection: Choose which GitHub repositories to connect so they appear in the Docs dashboard and feed Q&A, changelog, and Friday Recaps. - Per‑repo automation controls: Manage automation behavior per repository from the Docs dashboard. ## Tips - Make sure the person connecting repos has permission on GitHub to authorize access to those repositories. - If a teammate can’t see the workspace after accepting, have them sign out and use “Sign in with GitHub” again to complete the redirect back to the Docs dashboard. - You can add more repositories later; newly connected repos will populate the dashboard and related views once authorized.