# Platform and developer tools ## Platform and developer tools Platform and developer tools are the routes for platform administration, developer references, code-parser availability, marketing-page generation, and automatic project claiming. | If you need to… | Go to… | |---|---| | Search for an organization and open its record | [Find an organization](#find-an-organization) | | Change a plan or repair SSO | [Manage plan and SSO settings](#manage-plan-and-sso-settings) | | Create and review a marketing page | [Generate and review a marketing page](#generate-and-review-a-marketing-page) | | Check the code-parser status or review interface examples | [Use the parser and developer reference surfaces](#use-the-parser-and-developer-reference-surfaces) | | Continue organization administration | [Manage organization access](doc:manage-organization-access) | | Review security and audit access | [Security and audit access](doc:security-and-audit-access) | | Follow generation stages | [Documentation generation lifecycle](doc:documentation-generation-lifecycle) | | Continue work on a claimed project | [Projects overview](doc:projects-overview) | | Resolve a shared application error | [General error messages](doc:general-error-messages) | These tools sit alongside the main project and operations work areas. Use the platform routes when you administer an organization, the marketing-page route when you turn existing project documentation into a page, and the developer routes when you need a reference surface or an automatic handoff. ## Before you start You need a signed-in session before these routes can load their data. Platform organization administration requires platform-administrator access. The organization list uses the access token from that session, and the organization detail page loads the organization and its SSO information with the same access token. Before changing an organization, have the organization record open and decide which plan or SSO setting you need to change. Keep the audit reason ready: plan changes and SSO changes each require one. The organization’s current SSO configuration determines whether its SSO fields are available, and its current SSO status determines whether **Disable SSO** is available. Before generating a marketing page, open the Marketing Pages area with a current project selected. The wizard uses that project for the generation job. Decide the audience, voice, and page sections before you reach the confirmation step. ## Find an organization An organization record is the place where platform administrators review and change one organization’s plan and SSO settings. **Prerequisites** - You are signed in with platform-administrator access. - You know part of the organization name, slug, or organization ID, or you know which plan to filter. **Steps** 1. In the platform organization list, enter text in **Search name, slug, or org ID**. 2. Choose a plan from the plan filter when you want to narrow the list. | If you need to… | Choose… | |---|---| | See every plan | `All plans` | | Find free organizations | `FREE` | | Find professional organizations | `PRO` | | Find business organizations | `BUSINESS` | 3. Select **Search**. 4. Select the organization row you want to inspect. If no row matches, the page displays “No organizations match”. Clear the search or plan filter, then select **Search** again. **Result:** The organization record opens. ## Understand the organization record The organization record has a Plan panel for subscription settings and a Single Sign-On panel for repairing an organization’s SSO configuration. The Plan panel contains the organization’s current plan information, an audited reason, a trial override area, and a base-plan area. The trial-plan choices are `FREE`, `PRO`, and `BUSINESS`. The base-plan choices are `Choose…`, `FREE`, `PRO`, and `BUSINESS`. The Single Sign-On panel can contain **IdP SSO URL**, **IdP EntityID / issuer**, **Allowed domains (comma-separated)**, and **Reason (audited)**. When SSO is not configured, the panel displays `No SAML configuration for this org.`. When SSO is enabled, **Disable SSO** appears. **Set base plan** remains unavailable until a base plan is selected. ## Manage plan and SSO settings Use this procedure when you need to change an organization’s plan or repair its SSO configuration. Each change carries an audit reason. **Prerequisites** - You have platform-administrator access. - The organization record is open. - You know the reason to record for the change. **Steps** 1. In the Plan panel, enter the audit reason in **Reason (required — audited)**. 2. Choose one plan action. | If you need to… | Do this… | |---|---| | Grant a trial override | Choose `FREE`, `PRO`, or `BUSINESS`, set **Trial duration** from `1` to `365` days, then select **Grant trial**. | | Remove an existing override | Select **Clear override**. | | Set the base plan | Choose `FREE`, `PRO`, or `BUSINESS` in **Base plan**, then select **Set base plan**. | 3. Choose one SSO action. | If you need to… | Do this… | |---|---| | Save an SSO repair | Enter the provider address in **IdP SSO URL**, the provider identifier in **IdP EntityID / issuer**, comma-separated domains in **Allowed domains (comma-separated)**, and the reason in **Reason (audited)**. Select **Save SSO config**. | | Disable enabled SSO | Select **Disable SSO**, then enter the requested reason. | If you submit a plan change without a reason, the page displays `A reason is required (it is audited).`. If you submit an SSO change without its reason, it displays `A reason is required for SSO changes.`. **Result:** A successful plan change displays `Plan updated.`. A successful SSO repair displays `SSO config saved.`. A successful disable action displays `SSO disabled.`. ## Generate and review a marketing page A marketing page is a generated page assembled from the documentation in the current project. Configure its audience, voice, and sections before reviewing its variants. **Prerequisites** - A current project is selected. - You know the audience the page addresses. - You know which sections the page needs. **Steps** 1. In Marketing Pages, select **Generate new page**. 2. Enter the intended audience in **Target Audience**. 3. Choose one **Brand Voice** option. | If you want the page to sound… | Choose… | |---|---| | Professional | `Professional` | | Bold | `Bold` | | Empathetic | `Empathetic` | | Technical | `Technical` | | Casual | `Casual` | 4. Select **Next: Choose Sections**. 5. Select the sections to include. | If you need to include… | Select… | |---|---| | The main hero area | `Hero` | | Pain-point identification | `Problem` | | A product feature grid | `Features` | | A step-by-step workflow | `How It Works` | | Testimonials and logos | `Social Proof` | | Pricing tiers | `Pricing` | | Frequently asked questions | `FAQ` | | A final call to action | `CTA` | 6. Select **Next: Confirm**. 7. Review the generation summary. 8. Select **Generate Page**. 9. Follow the progress display through its stages: `Setting up`, `Researching documentation`, `Writing marketing copy`, `Creating visuals`, `Building the page`, and `Final touches`. 10. When the page is complete, select **Review Variants**. 11. Select a variant. 12. Select **Preview Full Page**. 13. In the variant list, select **Select** for the variant you want to use. The wizard requires at least one section before **Next: Confirm** can continue. If no project is selected, submitting the wizard does not start a job. A failed generation displays `Generation Failed` and `An unexpected error occurred.` when no more specific error is available. If no variants are available, the variant screen displays `No variants available.`. If there is no page to preview, the preview screen displays `No page to preview.`. **Result:** The generated page reaches the variant review area, where you can select a variant and open its full-page preview. ## Use the parser and developer reference surfaces The Code Parser route is a placeholder for future code-analysis work. The Kit route is a reference sheet for interface primitives, and the claim route performs an automatic handoff after a trial project is claimed. The Code Parser page displays **Code Parser**, `Coming soon`, and `Parse and analyze code to generate documentation automatically.`. The page has no upload or analysis action. The Kit reference sheet demonstrates buttons, chips, segmented controls, tabs, tables, menus, modals, notes, and empty states. Its demonstrations include **Open modal**, **Open menu**, **Success toast**, and **Error toast**. The demonstration messages include `Documentation published`, `Generation failed — job 4821`, `Deleted (not really)`, and `Nothing was deleted — this is the kit page.`. The claim route starts automatically after sign-in. On success, it sends you to the claimed project. If the trial cannot be claimed, it displays **Claim failed.** and one of these messages: `This trial project could not be claimed — it may have expired or already been claimed.`, `Claim failed.`, or `Something went wrong while claiming the project. Please try again.`. ## When a platform tool goes wrong Use the message on screen to choose the next action. | What you see | Meaning | Next action | |---|---|---| | `Not authorized.` | The platform request was refused for access reasons. | Use an account with platform-administrator access. | | `Failed to load organizations.` | The organization list could not load. | Return to the platform list and try the request again. | | `A reason is required (it is audited).` | A plan action has no audit reason. | Enter **Reason (required — audited)**, then submit the plan action again. | | `A reason is required for SSO changes.` | An SSO change has no audit reason. | Enter **Reason (audited)**, then select **Save SSO config** again. | | `No SAML configuration for this org.` | The organization has no SAML configuration in the SSO panel. | Use the organization’s SSO settings to configure SSO before repairing it here. | | `Generation Failed` | The marketing-page generation reached a failed state. | Read the message below the heading, then return to the dashboard. | | `No variants available.` | The variant screen has no variants to select. | Return to the dashboard. | | `No page to preview.` | The preview screen has no page to display. | Return to the variant list. | | **Claim failed.** | The automatic trial-project claim did not complete. | Use the available recovery route. | | `This trial project could not be claimed — it may have expired or already been claimed.` | The trial project is unavailable for claiming. | Start the claim flow again with an available trial project. | | `Claim failed.` | The claim operation failed without a more specific message. | Follow the claim flow again. | | `Something went wrong while claiming the project. Please try again.` | The claim request encountered an unexpected problem. | Try the claim flow again. | ## What to do next After opening an organization, continue with [Manage organization access](doc:manage-organization-access) for organization administration or [Security and audit access](doc:security-and-audit-access) for security and audit work. After a marketing-page generation, follow [Documentation generation lifecycle](doc:documentation-generation-lifecycle) for its stages, then continue in [Projects overview](doc:projects-overview). For shared application failures, use [General error messages](doc:general-error-messages).