Skip to content

chore: make agent path more prominent in app creation docs - #454

Merged
adidottxt merged 9 commits into
mainfrom
adi/run-4007-chore-make-the-agent-path-more-prominent-in-the-app-creation
Aug 13, 2026
Merged

chore: make agent path more prominent in app creation docs#454
adidottxt merged 9 commits into
mainfrom
adi/run-4007-chore-make-the-agent-path-more-prominent-in-the-app-creation

Conversation

@adidottxt

@adidottxtadidottxt commented Aug 12, 2026•
edited
Loading

Copy link
Copy Markdown
Contributor

This PR updates our docs to prioritize the agent path for Porter's hosted MCP server and its create_app tool for creating an application.

This is done in a few ways:

  • adding a shared Agent tab (snippets/agent-create-app.mdx) to the quickstart and GitHub deploy pages. Agent is first and default (the tab states the Porter GitHub App prerequisite), and also gives a copy-pasteable prompt, and explains the merge-the-PR step.
  • promoting the GitHub App prerequisite to its own page, applications/deploy/connect-github, linked from both the Agent and Dashboard paths.
  • trimming applications/deploy/overview to concepts and adds reciprocal links from the MCP docs.
  • adding agent-only guidance to each touched page via <Visibility for="agents">, so .md/llms.txt exports steer agents to create_app.

I also setup some evals in #455: agent guidance in the top two results went from 1/4 to 4/4 generic queries, median tokens before agent guidance dropped 53.8%, and 18/18 Claude trial answers lead with create_app (+13 over production).

@mintlify

mintlifyBot commented Aug 12, 2026•
edited
Loading

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

ProjectStatusPreviewUpdated (UTC)
porter🟢 ReadyView PreviewAug 12, 2026, 4:06 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

@adidottxt
adidottxtforce-pushed the adi/run-4007-chore-make-the-agent-path-more-prominent-in-the-app-creation branch from f2b0896 to 229ae4eCompareAugust 12, 2026 16:39
@adidottxt

adidottxt commented Aug 12, 2026•
edited
Loading

Copy link
Copy Markdown
ContributorAuthor

Superseding the earlier Context7-pending note: the strict before/after evaluation now passes without relying on Context7 as the primary harness.

MeasureProductionPreview
Generic queries with agent guidance in the top two1/44/4
Median tokens before first agent guidance1047.5484
Agent-aware queries with agent guidance first—2/2
Workflow queries retrieving the complete create_app path—2/2

That is a 53.8% reduction in context before the agent path appears. All six agent-only visibility checks pass.

The three-trial Claude outcome gate also passes: 18/18 preview answers lead with create_app (+13 over production), 6/6 workflow answers contain all required facts, and no answer recommends an invalid tool or claims MCP can install the GitHub App.

Context7 is retained as an optional site-wide spot check; the reproducible primary gate fetches and hashes production/preview llms-full.txt, uses the same frozen canonical page for each before/after query, and ranks a four-chunk context pack locally.

@adidottxt
adidottxtforce-pushed the adi/run-4007-chore-make-the-agent-path-more-prominent-in-the-app-creation branch 2 times, most recently from 409bf5d to 4178b8dCompareAugust 12, 2026 17:53
@adidottxt
adidottxtforce-pushed the adi/run-4007-chore-make-the-agent-path-more-prominent-in-the-app-creation branch from 4178b8d to bbb3edbCompareAugust 12, 2026 17:54
@adidottxt
adidottxt marked this pull request as ready for review August 12, 2026 18:07
@adidottxtadidottxt mentioned this pull request Aug 12, 2026
Draft
@adidottxtadidottxt changed the title chore: make the agent path more prominent in app creation docschore: make agent path more prominent in app creation docsAug 12, 2026
@adidottxtadidottxt mentioned this pull request Aug 12, 2026
Merged
MauAraujo
MauAraujo approved these changes Aug 13, 2026
View reviewed changes
Comment threadgetting-started/quickstart.mdx
Comment threadapplications/deploy/deploy-from-github-repo.mdx
Comment threadapplications/deploy/connect-github.mdx
@adidottxt
chore: lead the agent tab with a description instead of a header
6233d18
Address review feedback that the Agent tab opened directly on a heading
while the Dashboard and CLI tabs open with a lead-in sentence. Adds a
one-line description and converts the three sections to <Steps>.
@adidottxt
chore: let stated user intent override the agent hints
0e8bd96
Address review feedback that the agent hints should not push an agent
toward create_app when the user has asked for something else. Each
<Visibility for="agents"> block now leads with the exception — dashboard,
CLI, porter apply, or configuration-as-code — before stating create_app
as the default, and says not to author a porter.yaml otherwise.
@adidottxt
chore: add agent hint for the Docker registry deploy path
3b84a10
Agents fetching the registry page had no create_app guidance. Points them
at the image argument, and notes that it needs no pull request and no
GitHub App, unlike the source-and-build flow.
@adidottxt
adidottxt merged commit 6024d11 into mainAug 13, 2026
2 checks passed
@adidottxt
adidottxt deleted the adi/run-4007-chore-make-the-agent-path-more-prominent-in-the-app-creation branch August 13, 2026 19:53
@adidottxtadidottxt mentioned this pull request Aug 13, 2026
Merged
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@MauAraujoMauAraujoMauAraujo approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@adidottxt@MauAraujo