Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 88 additions & 3 deletions config/search/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,9 @@ this directory.
the existing indices through Algolia's settings UI or `setSettings` API.
Preserve settings not listed in the deltas. Put the same values in the
Crawler's `initialIndexSettings` for future new indices: those initial settings
do **not** update an existing index.
do **not** update an existing index. When introducing a grouping field such
as `section_url`, finish the crawl in step 7 and verify the field is present
before enabling that field on the existing index.
6. Copy [agent-instructions.md](agent-instructions.md) into this application's
Agent Studio agent prompt and [system-instructions.md](system-instructions.md)
into its System prompt editor. Apply the system prompt for testing, test both
Expand Down Expand Up @@ -55,6 +57,17 @@ this directory.
- Both indices omit blog listings, tag archives, and the site's search page.
Individual articles and API documentation remain included and receive their
own category labels. No client-side result filtering hides these sources.
- Keyword records carry `section_url`, the nearest containing level-two heading
with the record's edition and other query parameters preserved. Native Algolia
distinct grouping returns the best matching subsection within each section;
its actual result URL still points to that subsection. All source records stay
searchable. API entries and unknown anchors keep their individual URLs so
independent interfaces are not collapsed into an article section.
- Every API chunk in the AI index identifies itself as developer reference
material. Command names and preference keys alone do not establish visible
controls. An end-user guide must supply the access path; configuration advice
also needs the exact file, key, value, and scope. Keep this distinction in both
extraction and instructions rather than adding feature-specific prompt recipes.
- The rehype plugin adds `data-search-params` to headings inside query-enabled
Docusaurus tabs. Extraction combines that metadata with the exact section
anchor, for example `?edition=community#copy-your-picture`. Docusaurus itself
Expand Down Expand Up @@ -129,6 +142,8 @@ source guides so future documentation changes do not require prompt recipes.
| `find and replace` | The current-file walkthrough, opening Replace, entering both values, reviewing/replacing matches, and saving. Distinguish project-wide replacement without forcing both procedures into one answer. |
| `What does alt mean?` | A short explanation of the image description, with a small example if useful. Do not repeat the full image tutorial. |
| `Show the Image Gallery screenshot from the tutorial` | A relevant source screenshot that loads, meaningful alternative text, a separate full-size link, and the source guide. Check that it fits the desktop and mobile answer panel. |
| `I cannot find Auto Update in Help` | Never infer a menu from `HELP_AUTO_UPDATE`. Once the updated Managing App Updates guide is deployed and crawled, explain the desktop `autoUpdate` preference in `phcode.json`, valid JSON, saving, and its limits. Until that evidence is retrieved, state the documentation gap without guessing a setting or substituting an update-server setup. |
| A request for an undocumented scheduled sync control | Search the docs, distinguish missing evidence from an impossible feature, and avoid invented menus, intervals, or configuration keys. Ask for the visible label if needed; do not turn related Git or publishing features into the requested control. |

Retain modes, dialogs, locations, and saving when shortening prose. A documentation
link can provide screenshots and optional practice files; it should not replace
Expand Down Expand Up @@ -427,8 +442,8 @@ Prompt changes alone cannot restore an icon absent from the retrieved source.
Its agent ID is unchanged, so this model switch does not require a site build.
The separate production key has no expiry; billing uses the manually funded
prepaid balance. Automatic top-ups remain off. No secret is stored in this
repository. The former Azure `gpt-6-luna` provider remains available for rollback
through Agent Studio; save and reload after any provider change.
repository. The former Azure `gpt-6-luna` provider was subsequently removed in
the production-only cleanup recorded below; it is no longer a rollback option.
- Live browser checks confirmed the new model/key were used, source screenshots
loaded, HTML was highlighted, and tested source links returned HTTP 200. A model
switch does not repair missing or misleading source evidence. The earlier
Expand Down Expand Up @@ -460,12 +475,82 @@ Prompt changes alone cannot restore an icon absent from the retrieved source.
lockfile, and the maintained `5.2.0-phcode.2` build agree; no package upgrade
was needed.

### Production cleanup and grounding follow-up on 18 November 2026

- Removed the seven unused draft/benchmark agents and the unused OpenRouter test
and Azure providers from Algolia. Only the published documentation agent and
`Phoenix Docs Sonnet Production` provider remain. The two production indices
and crawler are retained; no public MCP server was configured. This cleanup
did not revoke keys or change billing in external provider accounts. Do not
recreate test endpoints during routine QA: use the retained agent's unsaved
preview, then save only the reviewed instructions.
- The earlier control-icon website release is deployed. Its extraction and
prompt guidance were applied, crawled, and checked in fresh live answers.
The earlier pending-deployment and draft-prompt statements above describe
their respective checkpoints, not the current production state.
- Checked the current Phoenix `prod` source at
`1cd3f2f3d59dc19f44c3d70d038728a6e5ba9959`. Both desktop updater implementations
register `HELP_AUTO_UPDATE` but do not add it to Help. They read the `autoUpdate`
preference; a pending update and some checks can precede that preference gate.
Added the precise desktop preference workflow and limitations to
[Managing App Updates](../../docs/09-Schools%20%26%20Workplaces/03-managed-updates.md).
This guide change is local and still needs website deployment and a recrawl.
Do not claim that the live assistant can already retrieve its new instructions.
- Published and read back the new extraction actions and `initialIndexSettings`.
The completed crawl had 252 successful URLs, 43 ignored URLs, and no failures;
it retained 5,449 keyword records and 203 AI records. All 116 API records carry
the source-context label, and no AI record contains embedded image data.
A 1,000-record keyword sample had no missing `section_url`; sampled API entries
retained their exact URL as the grouping key. The managed configuration,
schedule, scope, and 30% record-loss safeguard were preserved.
- After the refreshed records were live, changed only the existing keyword
index's distinct attribute from `url` to `section_url`. Its one-way
`find and replace → replace text` synonym remains. All 15 cases in
[evaluation.json](evaluation.json) passed. Styles Bar's Text Color section
moved from fourth to second for `text color` and `text colour`; font size and
Python terminal remained first. The actual full search page also showed the
corrected ordering. A tested proximity-first ranking candidate harmed font
results and was rejected; no query-specific boost or client-side filtering
was introduced.
- Saved and reloaded both reviewed prompts, confirming exact matches with this
directory. The production provider/model and tools were retained. Preview
checks covered image insertion, an `alt` follow-up, Community replacement,
an undocumented scheduled-sync control, the missing auto-update switch, and
a change of topic to project-wide replacement. The image workflow kept both
editions, required controls, loaded icons, and two screenshots; replacement
kept Highlight Mode and editing the existing tag. The follow-up did not repeat
the tutorial. Unsupported-control samples did not invent a menu or config key.
Earlier candidates reproduced an unrelated administrator procedure; the final
instructions instead link adjacent material without substituting its steps.
- These are sampled improvements, not a guarantee of concise or error-free
answers. Some responses still include extra explanation and repeated searches.
The current auto-update response acknowledges the missing end-user procedure;
retest it after deploying and crawling the new guide. Record visible answer
outcomes without saving raw diagnostic request/response traffic that may
include private configuration.
- A fresh answer on the deployed search page retained the Pro and Community
insertion workflows, two loaded screenshots, six source-backed control icons
(including the lightning bolt), highlighted HTML, and encoded source links.
At 390 px, the screenshots fitted the panel, icons remained 20 px, and neither
the page nor panel overflowed horizontally. The answer still labeled the Pro
description step optional; keep checking source completeness rather than
treating visual rendering or answer length as a complete quality score.
- The live npm registry and official release notes were checked again:
DocSearch `5.2.0` and Docusaurus `3.10.2` are still the latest stable versions.
Manifest, lockfile, and maintained `5.2.0-phcode.2` upstream provenance agree;
no dependency upgrade was needed. All 38 search tests and 14 tutorial/link
tests passed, along with packaging, the production build, and generated
search, tutorial, and local-link checks. Existing unrelated anchor/blog
warnings remain. The new preference instructions were reviewed at desktop
and 390 px widths with no horizontal overflow.

## Official references

- [Docusaurus query-string tabs](https://docusaurus.io/docs/markdown-features/tabs#query-string)
- [Algolia extraction actions](https://www.algolia.com/doc/tools/crawler/apis/configuration/actions/)
- [Algolia initial index settings](https://www.algolia.com/doc/tools/crawler/apis/configuration/initial-index-settings/)
- [Algolia attribute ranking strategies](https://www.algolia.com/doc/api-reference/api-parameters/attributeCriteriaComputedBy)
- [Algolia distinct grouping attribute](https://www.algolia.com/doc/api-reference/api-parameters/attributeForDistinct)
- [Algolia response caching and cost controls](https://www.algolia.com/blog/product/guardrails-agent-studio)
- [Google robots metadata](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag)
- [Docusaurus postBuild lifecycle](https://docusaurus.io/docs/api/plugin-methods/lifecycle-apis#postbuildprops)
Expand Down
5 changes: 4 additions & 1 deletion config/search/agent-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,16 @@ You help people use Phoenix Code, the code editor for developers, designers, and
- Start with a focused query for the user's goal and `number_of_results: 3`. Do not introduce unestablished context or send a long list of loosely related keywords. Search again when results only partly match or more evidence is needed to answer all parts.
- Prefer guides and feature documentation that explain the actual task. A listing, release summary, FAQ, or overview pointing elsewhere is not the complete procedure. Read the referenced detailed sections, including prerequisites and controls, before answering.
- Retrieve the documented editor workflow before falling back to generic code for a task in Phoenix Code. Verify its edition, platform, mode, selected element or file type, and limitations. Do not transfer a control from a related feature without evidence.
- Separate developer interfaces from user controls. An API command, preference key, or translated label does not establish a visible menu item or switch. UI instructions need a documented access path; configuration edits need the exact supported key, value, file, and scope. Do not turn an API identifier into a guessed menu path or advise changing an unidentified setting.
- Treat edition metadata and Pro Feature notices as authoritative. An absent edition label does not mean free; a Pro-only source does not establish a Community method. Retrieve a documented alternative when needed.
- General programming and web-development questions are welcome. Answer them directly from reliable knowledge, with a usable example or authoritative reference when useful. Distinguish that knowledge from documented product behavior. Explain the scope briefly for unrelated requests, without a canned refusal.
- If focused searches cannot establish a product detail, identify the gap and offer a supported next step. Do not guess controls, shortcuts, or links.
- If focused searches cannot establish a product detail, state the specific gap briefly and give one useful next step. Do not list unrelated platform behavior, speculative reasons, or every unsuccessful source. Do not substitute a complex adjacent workflow that does not achieve the requested result; a related guide can be linked without reproducing its procedure. Do not guess controls, shortcuts, or links.
- Stop searching when further results only repeat the same internal symbols or unrelated guides. Explain the specific evidence gap instead of expanding into tangential searches or speculating about hidden settings.

## Explain what the reader needs

- For procedures, apply the System prompt's action-preservation check to every workflow. Adapt the source to the user's goal and current state while retaining each necessary interaction. Preserve panel/dialog access, selection, confirmation, and saving; do not replace these actions with a description of the desired result. Include a result check.
- Organize a walkthrough around meaningful stages, combining adjacent actions when their controls and order stay clear. Use compact numbered steps instead of a separate step for every click. Leave out optional layout changes, repeated checks, and unrelated alternatives unless they solve the user's problem. Keep a necessary assumption brief; do not append another file-type workflow or a general troubleshooting list by default.
- Show Phoenix Pro first and Community (free) second when documented workflows differ and no edition was chosen. Apply this to each relevant part of a multi-part request. Honor an explicitly chosen edition; explain shared workflows once.
- For troubleshooting, order useful checks using the symptoms and context. Distinguish confirmed facts from possible causes. Ask only for information needed for the next diagnostic decision.
- For explanations, comparisons, and narrow follow-ups, answer the point directly without repeating unrelated procedures. Use examples or tables when useful. Keep similar operations distinct according to the actual goal.
Expand Down
3 changes: 3 additions & 0 deletions config/search/evaluation.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
[
{"query":"text color","expectedPath":"/docs/Pro%20Features/styles-bar#text-color","maxRank":3},
{"query":"text colour","expectedPath":"/docs/Pro%20Features/styles-bar#text-color","maxRank":3},
{"query":"change font size","expectedPath":"/docs/tutorials/edit-text-fonts?edition=pro#pro-change-font","maxRank":3},
{"query":"python terminal","expectedPath":"/docs/tutorials/run-python#3-open-the-terminal","maxRank":3},
{"query":"how to change input text colors","expectedPath":"/docs/editing-colors#change-input-text-colors","maxRank":5},
{"query":"find in files","expectedPath":"/docs/Features/find-in-files","maxRank":1},
{"query":"find and replace","expectedPath":"/docs/tutorials/find-and-replace","maxRank":3},
Expand Down
24 changes: 22 additions & 2 deletions config/search/records.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,22 @@ function extractSearchRecords({$, url, helpers}, format, resolveTabUrl) {
path.startsWith('/videos/') ? 'Videos' : 'Documentation';
const language = $('meta[name="docsearch:language"]').attr('content') || 'en';
const parametersByAnchor = Object.create(null);
const sectionsByAnchor = Object.create(null);
const editionSections = [];
const explicitEditions = ($('meta[name="docsearch:edition"]').attr('content') || '')
.split(',').map(value => value.trim()).filter(value => ['pro', 'community'].includes(value));
let introductoryProNotice = false;
let reachedSection = false;
const contentRoot = $('main article').length ? $('main article').first() : $('main').first();
let sectionAnchor = '';
contentRoot.find('h1[id], h2[id], h3[id], h4[id], h5[id], h6[id]').each((_, element) => {
const heading = $(element);
const tag = element.tagName || element.name;
const anchor = heading.attr('id');
if (tag === 'h1') sectionAnchor = '';
if (tag === 'h2') sectionAnchor = anchor;
sectionsByAnchor[anchor] = sectionAnchor || anchor;
});
contentRoot.find('h2, h3, h4, h5, h6, .theme-admonition').each((_, element) => {
const node = $(element);
// A Pro note inside a tab or a later section qualifies that section only.
Expand Down Expand Up @@ -93,6 +103,13 @@ function extractSearchRecords({$, url, helpers}, format, resolveTabUrl) {
const recordUrl = resolveTabUrl(record.url, parametersByAnchor);
const target = new URL(recordUrl, pageUrl);
const selectedEdition = target.searchParams.get('edition');
let anchor = target.hash.slice(1);
try { anchor = decodeURIComponent(anchor); } catch (error) { /* Keep malformed anchors distinct. */ }
const section = new URL(target);
// Keep the best matching nested heading for each article section. All
// records remain searchable, and different edition queries stay separate.
// API entries are independent interfaces, even under a shared heading.
if (category !== 'API' && sectionsByAnchor[anchor]) section.hash = sectionsByAnchor[anchor];
target.hash = '';
return {
...record,
Expand All @@ -103,6 +120,7 @@ function extractSearchRecords({$, url, helpers}, format, resolveTabUrl) {
} : {}),
url: recordUrl,
url_without_anchor: target.href,
section_url: section.href,
};
});
}
Expand Down Expand Up @@ -207,6 +225,8 @@ function extractSearchRecords({$, url, helpers}, format, resolveTabUrl) {
const availability = edition === 'pro' ? 'Edition availability: Phoenix Pro only.\n\n' :
edition === 'community' ? 'Edition availability: Community (free).\n\n' :
edition === 'mixed' ? 'Edition availability: this page has separate Phoenix Pro and Community (free) sections.\n\n' : '';
const sourceContext = category === 'API' ?
'Source context: developer API reference. Command identifiers, functions, and preference keys describe code interfaces. Their presence does not establish a visible menu item, shortcut, or settings control. User-interface availability and access paths need separate end-user documentation.\n\n' : '';
const records = helpers.splitTextIntoRecords({
text,
baseRecord: {
Expand All @@ -220,11 +240,11 @@ function extractSearchRecords({$, url, helpers}, format, resolveTabUrl) {
docusaurus_tag: tags.split(',').map(value => value.trim()).filter(Boolean),
editionSections,
},
// Reserve room for the repeated edition label in every returned chunk.
// Reserve room for source context and the edition label in every chunk.
maxRecordBytes: 99000,
orderingAttributeName: 'part',
});
return records.map(record => ({...record, text: availability + record.text}));
return records.map(record => ({...record, text: sourceContext + availability + record.text}));
}

function extractDocSearchRecords(context) {
Expand Down
4 changes: 4 additions & 0 deletions config/search/settings.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,10 @@ const indexSettings = {
removeStopWords: ['en'],
minProximity: 2,
attributeCriteriaComputedBy: 'sum',
// Nested article headings should not crowd out other matching sections.
// section_url retains edition parameters; API entries keep their own URL.
attributeForDistinct: 'section_url',
distinct: true,
},
'markdown-index': {
attributesForFaceting: [
Expand Down
Loading
Loading