[MuHamza30]

The change

The root src/content/nav.json had one list, pages, and it carried two decisions: which top-level folders are tabs, and where Home's nodes go. Naming a folder in pages made it a tab, so a folder could never be ordered inside Home. Unnamed folders all fell together where ... stood, in alphabetical order, and the only way to order them was a parent folder, which moves every address below it.

The root file now has two lists. The plan is in .ai/plans/portal-config.md, sections 5 and 16, added by the first two commits on this branch.

{
  "title": "Overview",
  "tabs": ["tutorials", "apimatic:sdks", "apimatic:api"],
  "pages": ["index", "getting-started", "authentication", "guides", "apimatic:plugin", "..."]
}

• tabs lists the tabs after Home, in order, and nothing else is a tab: a folder directly under content/, api or apimatic:api, apimatic:sdks and apimatic:plugin. It is valid only in the root file.
• pages orders Home's sidebar, as every other nav.json orders its folder. A folder named here is a group inside Home, and a token stands for its section. What pages does not name follows in Fumadocs' order: alphabetical, pages before folders, a section among the folders like any other.
• Home alone. A file with no tabs, "tabs": [] or no file at all makes no tab, so Home is the only tab and the header shows no tab bar. Every section keeps its address inside Home.
• A fresh portal keeps its tabs. The scaffold and the sample repository's root file name the three sections in tabs, so a portal from quickstart looks as it did.

Commits

1. Template. navigation-schema.ts extends Fumadocs' metaSchema with tabs, and the docs collection validates nav.json against it, so the key is no longer stripped. groupIntoTabs makes tabs from tabs, keeps a section pages names in Home, and orders the tabs through reorder. portalTabs returns no tab for Home alone.
2. CLI. PortalNavigation validates tabs: a page, ..., a folder serving /, an unknown name, a duplicate, and a node also in pages are each refused with their own sentence, and tabs below the root is refused. The root pages accepts the tokens and a folder serving /. The content tree names tabs from tabs and leaves sections placed in Home out of the shared-name warning. The notice naming the folders made into tabs is removed, and makesSameTabsAs becomes makesSameSectionsAs. The default fixture moves its tabs to tabs.
3. E2e and README. A new sections-in-home fixture and build, and the README's tabs bullet rewritten.
4. SonarCloud. Shared e2e helpers, a table-driven test and a split function, for the duplication and complexity it flagged.
5. First review. The scaffold writes tabs beside pages; a misspelt setting at the root is answered with tabs among the settings; the README states the real default for an unnamed section; unnamed sections follow everything tabs names; api in tabs is refused beside a page of that name; a mistyped tab is pointed at what tabs accepts.
6. Second review. A section tabs did not name used to keep a tab at a default place, so {} gave Home and three tabs while every folder went into Home. Now tabs is the whole tab bar: a section it does not name is a folder in Home, in Fumadocs' order, and reorder loses its bands and anchor. A root file with no tabs reads as an empty list, so the refusal of a 2.0.0-beta.1 file goes with the ambiguity it guarded. The scaffold and the sample repository (Name the three generated sections as tabs in nav.json sample-docs-as-code-portal#15) name the three sections in tabs. README and plans updated.

No BREAKING CHANGE: footer: nav.json is new since 1.x, so nothing breaks against the last stable release. The next beta's release notes should say what changed for a beta.1 root file: a folder or token its pages named is in Home until tabs names it.

Checked

• The unit suite passes: 1547 passing, 47 pending.
• tsc -p test/tsconfig.json, and ESLint and Prettier on the touched files, pass.
• E2e: all three builds pass, 47 cases. The default build keeps its four tabs from tabs; the branded build, which has no nav.json, renders no tab bar and serves every section inside Home; the sections-in-home build is unchanged.

🤖 Generated with Claude Code

[sohail2721]

Three findings from a review of this branch, each reproduced against 20543bb with both transformers applied. The first two look like bugs, the third is a usability gap in the error text.

[sohail2721]

Second pass on 0f9900a. The three earlier findings are fixed and their tests pin the cases; the full unit suite passes on this head after a build. Three further findings below: one worth fixing before merge (the README line endings), two minor.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[saeedjamshaid]

Reviewed at b387807c. The behaviour matches the plan. Two things I'd want before merge: a word to projects that lose their tabs on upgrade (inline at portal-navigation.ts:123), and the prompt text below that still assumes every section is a tab. The rest are code-quality points against the standard #374 set, most of them one rule living in several places.

Two points sit outside the diff:

• src/prompts/portal/serve.ts:54 still says removing the plugin block "removes the Context Plugin tab". The plugin is a tab only when tabs names it.
• src/prompts/portal/source.ts:315-316 still says "the tabs of the SDK pages and the context plugin keep their names".

On #374's sixth principle nothing changes: PortalNavigation worded its errors itself before this PR too. NearMiss is a step toward keying them by kind, though suggestion and tabSuggestion still word their sentences inside the type.

[MuHamza30]

The two points outside the diff are reworded in 0fb23fd: removing the plugin block removes the Context Plugin pages, and the shared-name warning says the SDKs and Context Plugin sections keep their names.

Each finding has a commit of its own from 001ca25 to d7c46c4. On the new head the unit suite passes (1559), the three e2e builds pass (47), and typecheck, ESLint and Prettier are clean.

[saeedjamshaid]

Second pass at 019ec6f7. 12 of the 13 threads are fixed as asked, and I've resolved them; the alphabetical-order one stands as decided. One fix brought in a new refusal, inline below. Two minor points, neither blocking:

• The no-tabs warning names the generated sections and the API reference, but in beta.1 a user folder the root pages named was a tab too. A beta.1 project with {"pages": ["index", "tutorials", "..."]} that follows the warning's "tabs" line loses its Tutorials tab without a word. Naming those folders in the suggested line would cover it.
• TabEntry (portal-navigation.ts:68) and TabOwner (portal-tabs.ts:7) still share three kinds (API reference, section, folder), differing in a folder's name against its directory, plus Home. Much smaller than before; fine to leave if the split is wanted.

[MuHamza30]

The two minor points and the plan correction, each in its own commit:

• 4cbbdb7: the no-tabs notice names the folders the root pages named as well, and its suggested line leads with them in pages order, as beta.1 showed them. A (group) folder serving the home page is left out, since tabs refuses it. Under portal serve a folder newly named gives the notice again, once.
• TabEntry and TabOwner stay split: TabOwner carries Home and a folder's directory, which the validator never has.
• 30e7885: the third-review entry now says a release that adds a section lands it alphabetically in Home in every existing portal, so that release must tell them to name its token; and a fourth-review entry records this round.

On the new head the unit suite passes (1560), and typecheck, ESLint and Prettier are clean.

[saeedjamshaid]

Third pass at 30e7885f. The apimatic:api fix and the plan correction are in, and I've resolved that thread; keeping TabEntry and TabOwner apart is fine for the reason given. One change left on the no-tabs notice, inline.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.7% Duplication on New Code

See analysis details on SonarQube Cloud

[MuHamza30]

QA testing plan

What changed

src/content/nav.json (the root one) now has a tabs list that decides the portal's tabs.

• tabs names the tabs after Home, in order. Only what is listed becomes a tab: a top-level folder by name, and the generated sections by token (apimatic:sdks, apimatic:plugin, apimatic:api or api).
• Home holds everything else: top-level pages, folders not in tabs, and sections not in tabs. pages orders Home's sidebar; title names the Home tab.
• No tabs, or no root nav.json: no tab bar at all (Home only). The build prints a warning with the exact line to add. "tabs": [] means "I want no tab bar" and prints nothing.
• A new portal is scaffolded with all three sections as tabs.
• Before this, every section and every folder named in pages was a tab automatically.

Scenarios

Tabs and layout

#	Setup	Expect
1	Fresh portal (scaffold), build	Tabs: Home, SDKs, Context Plugin (if plugin block), API Reference. Root nav.json has "tabs": ["apimatic:sdks","apimatic:plugin","apimatic:api"].
2	"tabs": ["guides", "apimatic:api"] with a content/guides/ folder	Tab bar: Home, Guides, API Reference, in that order. SDKs appear as a folder in Home's sidebar.
3	"tabs": ["apimatic:api", "guides"]	Same tabs, API Reference before Guides.
4	"tabs": ["api"]	Same as apimatic:api.
5	"tabs": []	No tab bar. Sections and folders all in Home's sidebar. No warning.
6	Root nav.json without tabs, e.g. {"pages": ["index", "..."]}	No tab bar. Build warns once, naming the sections now in Home and suggesting "tabs": [...] with their tokens. Pasting that line makes them tabs with no error.
7	No root nav.json at all	Same as 6, worded "There is no content/nav.json".
8	No tabs, but pages names a section, e.g. {"pages": ["index", "apimatic:sdks", "..."]}	Warning lists only what pages does not name (API Reference, plugin). If pages names all sections and api, no warning.
9	{"title": "Docs", "tabs": []}	Warning: the title shows nowhere because Home is the only tab. Build still succeeds.
10	{"title": "Docs", "tabs": ["apimatic:api"]}	Home tab is labelled "Docs". No warning.
11	Folder in tabs whose nav.json has a title	Tab shows that title; otherwise the folder name.
12	Section in Home ("pages": ["index", "apimatic:sdks"], not in tabs)	SDKs folder sits in Home's sidebar where pages puts it; /sdks still opens.

Errors (build must fail with a clear message)

#	Setup	Expect message about
13	"tabs": ["authentication"] where that is a page	A page cannot be a tab; use pages.
14	"tabs": ["..."]	... cannot be a tab.
15	"tabs": ["guides"] and "pages": ["guides"]	Named in both lists; keep one. Same for api in one and apimatic:api in the other.
16	"tabs": ["guides", "guides"]	Listed more than once.
17	tabs inside a subfolder's nav.json	Only read in the root file.
18	"tabs": ["apimatic:foo"]	Not a token; lists the valid ones.
19	"tabs": ["Guides"] or ["guides.md"]	Hint: did you mean guides?
20	"tabs": ["API"]	Hint: use api or apimatic:api.
21	"tabs": "guides" (not an array) plus a bad pages entry	Both errors reported in one run.
22	content/api.md exists and "pages": ["index", "api"]	Refused: api is the reference's mount point; rename the page.
23	content/api.md exists and "tabs": ["apimatic:api"]	Builds fine (the scaffold default must not break).
24	Empty folder (no pages) in tabs	Refused: folder has no page.

portal serve

#	Action	Expect
25	Start with no tabs, then save the file unchanged	Warning once at start, not again on each save.
26	While serving, add "tabs": [...]	Tab bar appears; no more warning.
27	While serving, add a plugin block with no tabs set	Warning repeats once, now naming Context Plugin too.
28	Introduce any error from 13-24 while serving	Error shown; preview keeps the last good build.

Upgrade

#	Setup	Expect
29	A 2.0.0-beta.1 project (root nav.json with pages only)	Builds, tab bar gone, warning from scenario 6. Adding the suggested line restores the section tabs. A folder that used to be a tab must be added to tabs by hand and removed from pages.

Also check: llms.txt / Copy Markdown still work, and the tab's first page opens correctly for the API Reference tab (operations grouped under folders).

🤖 Generated with Claude Code

[github-actions]

🎉 This PR is included in version 2.0.0-beta.3 🎉

The release is available on:

• npm package (@beta dist-tag)
• GitHub release

Your semantic-release bot 📦🚀