Skip to content
Merged

X #224

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
116 changes: 116 additions & 0 deletions config/search/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,34 @@ Test a new conversation after publishing prompts; an existing saved answer does
not regenerate. Prompt changes improve sampled behavior but do not guarantee that
every generated answer includes an image.

### Small control icons in answers

`TutorialIcon` keeps the actual Phoenix control shapes inline in the article.
The [tutorial-icons plugin](../../plugins/tutorial-icons/index.js) exports those
same shapes to `/img/tutorial-icons/` after a production build, including active
colors and the source/license files. The component supplies the exported URL in
`data-tutorial-icon-src`. During AI extraction, the Crawler replaces that SVG with
an image carrying its written control label, then restores the original DOM.
Without this conversion, Markdown retains the label but loses the SVG icon.

Use the shared component when documenting a control. Add new shapes and their
attribution to its existing icon map and `sources.json`; the export automatically
includes them. Do not maintain a separate set of AI icons, substitute emoji, or
teach the agent invented image paths. The answer uses an ordinary Markdown image
beside the written name, with empty alternative text when the label already names
the control. Scoped CSS keeps these images at text size in both themes. They are
separate from instructional screenshots and need no full-size link.

Deploy the website before applying the generated Crawler actions and recrawling.
In the hosted URL Tester, inspect a guide that uses the lightning bolt and another
control: its AI Markdown must contain absolute `/img/tutorial-icons/` image URLs
with the correct labels. Verify those images return HTTP 200, then test a fresh
Ask AI conversation. Check a wide light-theme answer and a narrow dark-theme
answer: the icons should load inline, retain the product's shapes, and leave the
text and screenshots readable. `npm run test:search` checks export/extraction;
`npm run verify:search` checks the built page annotations and exported assets.
Prompt changes alone cannot restore an icon absent from the retrieved source.

## Verification recorded on 18 November 2026

- The live npm registry and official release notes were checked: DocSearch
Expand Down Expand Up @@ -346,6 +374,92 @@ every generated answer includes an image.
Answer completeness remains a sampled quality limitation; no separate automated
review-and-repair stage is included in this release.

### Retrieval review and text/font tutorial on 18 November 2026

- Reviewed the text-editing and font-changing conversation that repeatedly
retrieved overlapping feature guides. Added
[Edit text and change fonts](../../docs/10-Tutorials/09-edit-text-fonts.md)
as a complete beginner walkthrough: Phoenix Pro's visual controls first,
Community's HTML/CSS alternative, and the existing Trail Notes practice ZIP.
The guide distinguishes website fonts from the editor font and explains why
Pro's inline styles can override the Community stylesheet example.
- Captured four original 1360 × 900 screenshots in Phoenix Code for the web on
18 November 2026, using a fresh `first-website` project copied from the
repository's practice files. Verified direct text editing in Design Mode,
System → Arial, 40 px sizing, saved inline HTML, Highlight Mode's matching
heading, and the saved Community CSS result. The free workflow was tested
in the same licensed app; the screenshots do not imply a license switch.
- Tested retrieval-instruction candidates in Agent Studio without publishing
them. In the same-UI image comparison, the original used two searches and
retained the necessary controls; candidates used one but omitted gallery
access or editing-mode steps. A project-replacement request and its current-file
correction used two searches followed by one with either configuration.
These samples do not establish a reliable efficiency gain. All candidate
prompt changes were discarded. Reloaded Agent Studio and verified both
published prompts exactly match the retained repository files.
- The actual AI search tool response already excludes `_highlightResult`.
Its presence in a regular search API response is not evidence of duplicated
AI context. Dashboard aggregate token counts do not measure unique document
text or, by themselves, billing. No index-field truncation, retrieval cap,
model change, or procedure shortening was applied.
- For future comparisons, use the same interface and retained conversation
history for both configurations. A text-only API replay that drops prior
tool results is not comparable to the Agent Studio follow-up. Include new
phrasings and complete action reviews; an identical cached opening question
is not another independent quality sample.
- Live npm registry and official release notes checked again: DocSearch `5.2.0`
and Docusaurus `3.10.2` remain the latest stable versions. The installed and
locked `5.2.0-phcode.2` source build retains the documented fixes; no dependency
upgrade was needed.
- The 32 search tests and seven tutorial release tests passed, along with
practice packaging, the production build, and generated search, tutorial,
and local-link checks. Browser review covered both editions at desktop and
390 px widths, light/dark themes, loaded full-size screenshot links, and the
Community section URL selecting its tab. Existing unrelated build warnings
remain. The new guide still needs website deployment and an Algolia recrawl;
measure retrieval again once it is in the live index. It is not yet evidence
of better production answers.

### Sonnet and control-icon follow-up on 18 November 2026

- The live documentation agent now uses the `Phoenix Docs Sonnet Production`
OpenAI-compatible provider with `anthropic/claude-sonnet-5.5` through OpenRouter.
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.
- 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
auto-update benchmark still needs a documentation/grounding fix: the internal
API command is not evidence of a user-facing menu option.
- The new control-icon export retains all 19 original SVG shapes, with normal
and active variants, theme support, and attribution. All 36 JavaScript search
tests and 14 tutorial/link tests passed, along with practice packaging, the
production build, and generated search, tutorial, and local-link checks.
Existing unrelated anchor/blog warnings remain.
- A local fixture rendered the exported icons through the installed DocSearch
Markdown renderer and built stylesheet. Desktop light and 390 px dark checks
confirmed loaded 20 px icons, readable labels, and no horizontal overflow.
This is renderer verification, not a claim that the live AI index already
contains the new icon URLs. Deploy this website change, apply the generated
Crawler actions, and recrawl before checking icon use in fresh live answers.
- Shorter-answer experiments were saved in unpublished Agent Studio drafts and
checked against the prompts actually sent in preview requests. They produced
clearer action groups and some narrower follow-ups, but also omitted access
steps in one sample and favored replacement in a broad add-image request.
The original configuration also added unrequested alternatives. These samples
do not establish a reliable quality improvement, so the brevity changes were
not promoted. The repository retains the existing answer rules with only the
new source-backed icon guidance. Apply that guidance with the icon deployment;
the live agent still has its previous prompts. Do not publish the experimental
drafts as part of this release.
- The live npm registry and official release notes were checked again: DocSearch
`5.2.0` and Docusaurus `3.10.2` remain the latest stable releases. Manifest,
lockfile, and the maintained `5.2.0-phcode.2` build agree; no package upgrade
was needed.

## Official references

- [Docusaurus query-string tabs](https://docusaurus.io/docs/markdown-features/tabs#query-string)
Expand All @@ -354,3 +468,5 @@ every generated answer includes an image.
- [Algolia attribute ranking strategies](https://www.algolia.com/doc/api-reference/api-parameters/attributeCriteriaComputedBy)
- [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)
- [Color schemes in embedded SVG images](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-color-scheme#embedded_elements)
1 change: 1 addition & 0 deletions config/search/agent-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ You help people use Phoenix Code, the code editor for developers, designers, and

## Illustrate visual workflows

- When the source includes a control-icon image, show that exact image inline beside the control's written name at its first useful mention. Do not replace the product's icon with an emoji or invent its image path. These small control icons do not count toward the screenshot limit and do not need full-size links. Use empty image alt text when the adjacent label already identifies the control.
- Include a relevant screenshot from retrieved sources by default for a procedure involving visual controls. The user does not need to ask for pictures. Put it beside the actions it illustrates. Do not illustrate a code workflow with a visual-editor screenshot or use an image from the wrong edition.
- Usually include one useful screenshot per relevant workflow, at most two per answer. Explanations, narrow follow-ups, and workflows without a useful source image do not need pictures. Respect a request for text only. Never substitute a decorative image for procedural evidence.
- Use standalone `![Meaningful description](exact-image-url)` followed by a separate full-size link. Do not use HTML image tags or put image Markdown inside a code fence.
Expand Down
15 changes: 15 additions & 0 deletions config/search/records.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,21 @@ function extractSearchRecords({$, url, helpers}, format, resolveTabUrl) {
return null;
}
};
// Inline SVG geometry disappears during Markdown conversion. The component
// supplies a build-generated image URL for each actual control shape.
$('main svg[data-tutorial-icon-src]').each((_, element) => {
const icon = $(element);
const source = imageUrl(icon.attr('data-tutorial-icon-src'), true);
if (!source) return;
const target = new URL(source);
if (target.origin !== pageUrl.origin ||
!/\/img\/tutorial-icons\/[a-zA-Z][a-zA-Z0-9-]*\.svg$/.test(target.pathname) ||
target.search || target.hash) return;
const label = icon.closest('[data-tutorial-icon-label]').text().trim();
const image = $('<img>').attr('src', source).attr('alt', label ? `${label} icon` : 'Control icon');
icon.replaceWith(image);
restoreMedia.push(() => image.replaceWith(icon));
});
$('main img').each((_, element) => {
const image = $(element);
const source = image.attr('src');
Expand Down
2 changes: 2 additions & 0 deletions config/search/system-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,4 +25,6 @@ Honor a specified edition and platform. When documented workflows differ and no

Include a relevant retrieved screenshot for a visual workflow when available, unless the user requests text only. Match it to the edition and actions it illustrates. Use a standalone Markdown image and a separate full-size link with exact retrieved URLs. Never invent an image URL. Keep complete text instructions alongside it.

When a source supplies a small control-icon image, preserve it inline beside the written control label at its first useful mention. Use the exact source URL, never an invented icon path or an emoji substitute. Control icons do not need full-size links and are separate from screenshots. An empty alt text is appropriate when the adjacent text names the control.

Cite exact source URLs near the relevant explanation. Preserve encoding, query parameters, and fragments. Use a section fragment only when that exact target is present in the source; otherwise cite the page. Use language-labeled code fences. Choose other formatting to make the answer easy to follow.
Loading
Loading