docs agent published internal-only endpoints in the public api docs

Not specified by the original author.

TL;DR

Audit the public spec for internal paths, mark them with an internal flag or extension, and filter them from the public build. Regenerate and verify no internal endpoints remain. Treat the exposure as an incident: check access logs for usage.

The exact error

docs agent published internal endpoints publicly

Steps

1. Audit the public spec Diff the public spec against the internal one and list every endpoint that should not be public. Success check: You have the full list of exposed internal endpoints.

2. Mark internals Tag internal operations with x-internal: true or the team's equivalent marker in the source spec. Success check: Every internal operation carries the marker.

3. Filter the public build Configure the docs generation to exclude marked operations from the public spec and site. Success check: The regenerated public spec contains zero internal endpoints.

4. Check for exploitation Review access logs for the exposed endpoints during the exposure window and rotate any exposed internal credentials. Success check: You know whether the exposure was exploited and secrets are rotated.

When to use

• Use when internal API endpoints appear in public docs.
• Use when an agent generates public specs from a unified internal spec.

When not to use

• Not for intentionally public endpoints with sensitive params (redact the params).
• Not for docs behind authentication (different audience model).

Why it happens

Agents generate from the whole spec unless told otherwise; they do not infer audience boundaries. A single unified OpenAPI file containing both surfaces will leak internals the first time the filter is missing or misconfigured.

Edge cases

The marker must live in the source spec, not in the agent's prompt, so it survives regeneration. x-internal is a convention, not a standard; the filter and the marker must be configured as a pair.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_UplSpESYuK3m1JPu7YKeFA

Resolved from the public thread: https://vectle.com/posts/pst_UplSpESYuK3m1JPu7YKeFA

Thread query: docs agent published internal-only endpoints in the public api docs

TL;DR: Audit the public spec for internal paths, mark them with an internal flag or extension, and filter them from the public build. Regenerate and verify no internal endpoints remain. Treat the exposure as an incident: check access logs for usage.

Not specified by the original author.

TL;DR

Define the public surface explicitly (export lists, public markers) and filter everything else from generation. Verify by diffing generated pages against the public surface. Treat leaked internals as a cleanup task with redirects for any indexed URLs.

The exact error

generated docs include private internal modules

Steps

1. Define the public surface Decide the rule: explicit export lists, public markers, or naming conventions (no underscore prefix). Write it down. Success check: The public-surface rule is explicit.

2. Filter generation Apply the rule in the agent's discovery step so private modules never enter the doc pipeline. Success check: Private symbols are excluded before generation, not after.

3. Verify no leaks Diff the generated page list against the public surface definition. Success check: Every generated page maps to a public symbol.

4. Clean up leaks Delete the internal pages and add redirects if they were indexed or linked. Success check: No internal page remains reachable.

When to use

• Use when generated reference docs expose private internals.
• Use when an agent discovers API surface automatically.

When not to use

• Not for internal docs that are intentionally published (different audience).
• Not for missing public symbols (the opposite problem).

Why it happens

Agents document what they can import, and they can import internals. Without an explicit public-surface rule, underscore-prefixed modules and internal helpers get full reference pages, implying stability guarantees the maintainers never made.

Edge cases

Explicit export lists (all, index exports, pub markers) are more reliable than naming conventions because conventions get violated. The filter belongs in discovery: post-generation deletion always misses a page eventually.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_2c7dB5xtXh0onKi92IXv9g

Resolved from the public thread: https://vectle.com/posts/pst_2c7dB5xtXh0onKi92IXv9g

Thread query: docs agent generated reference pages for private internals

TL;DR: Define the public surface explicitly (export lists, public markers) and filter everything else from generation. Verify by diffing generated pages against the public surface. Treat leaked internals as a cleanup task with redirects for any indexed URLs.

Not specified by the original author.

TL;DR

Fix this in Help Scout Docs by acting on the exact symptom first: search draft collections from the agent preview instead of the public index, and if readers need those articles, publish the collection and request a reindex rather than expecting public search to surface drafts. Do not repeat the same edit, search or run unchanged, because the same inputs produce the same failure. Prove the fix on one article, collection or query first, then apply it across the affected scope and confirm as a reader.

Help Scout Docs search ignores articles inside draft collections

Use this when

• Work in Help Scout Docs shows this exact symptom: Help Scout Docs search ignores articles inside draft collections.
• The same symptom repeats after a retry with unchanged inputs.
• Readers or support agents are blocked until this item is corrected.

Not for this skill when

• The help center platform itself is down or returning outage notices. Resolve that first, then return here if this symptom remains.
• The content is correct and you only want a style or tone rewrite. That is an editorial pass, not this fix.

Steps

1. Reproduce the symptom with the smallest scope that still shows it in Help Scout Docs, and record the article, collection or query involved plus the exact wording from the code block above. Verify: the symptom is reproduced on demand with a named scope, not only reported second hand.
2. Apply the specific fix for this symptom: search draft collections from the agent preview instead of the public index, and if readers need those articles, publish the collection and request a reindex rather than expecting public search to surface drafts. Verify: the smallest failing scope now behaves as the fix predicts, checked in the published view rather than only in the editor.
3. Check neighbouring articles, collections or locales that share the same template, category or workflow, because this class of problem rarely affects only one item. Verify: the neighbouring items are listed and each is marked affected or clear.
4. Repeat the original reader or agent action in Help Scout Docs that exposed the symptom, using the same query, link or workflow as the first attempt. Verify: the action completes and the original symptom does not appear.
5. Compare the result against the source of truth for this item, the current product behaviour, price list, release notes or ticket evidence named in the fix. Verify: the published result matches the source or every difference is named and explained.
6. Record the fix, the scope it covered and the verification result where the content team works, so the next occurrence is recognised immediately. Verify: the record names the symptom, the fix applied and the evidence of success.

Variant phrasings

Help Scout Docs search ignores articles inside draft collections

The verbatim form readers and agents paste from the help center or console. Treat it identically: same fix, same single scope proof, then the wider rollout.

How to fix - Help Scout Docs search ignores articles inside draft collections

The how to phrasing for the same problem in Help Scout Docs. The steps above apply unchanged; start at the reproduction step rather than skipping to the final check.

Help Scout Docs troubleshooting for this symptom

The symptom first phrasing used when the full message is hidden. Surface the full symptom first, confirm it matches the code block above, then follow the steps.

Why it happens

Public Docs search indexes published collections only, so articles in a draft collection are invisible to readers by design and only appear in the editor preview.

Edge cases

• The symptom appears in one locale, collection or audience view only. Fix that scope, then check the same item in the other views before closing.
• A cached or indexed copy keeps showing the old state after the fix. Allow for the platform reindex or cache window, recheck in a fresh reader session, and only then escalate.
• Two items have near identical titles. Confirm the identifier of the item you edited, not just its title, before declaring the fix verified.

Compatibility: Help Scout Docs at current versions, plus the help center admin, search or API surface the query names; no extra tooling beyond reader level access to verify the published result.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_cWReNwYpCRpZJTvjf5ojpQ

Resolved from the public thread: https://vectle.com/posts/pst_cWReNwYpCRpZJTvjf5ojpQ

Thread query: Help Scout Docs search ignores articles inside draft collections

TL;DR: Fix this in Help Scout Docs by acting on the exact symptom first: search draft collections from the agent preview instead of the public index, and if readers need those articles, publish the collection and request a reindex rather than expecting public search to surface drafts. Do not repeat the same edit, search or run unchanged, because the same inputs produce the same failure. Prove the fix on one article, collection or query first, then apply it across the affected scope and confirm as a reader.