Skip to content
Merged

X #223

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
2 changes: 2 additions & 0 deletions .github/workflows/build-verify.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ jobs:
run: npm run test:tutorials
- name: Test link verification
run: npm run test:links
- name: Test search links and DocSearch fixes
run: npm run test:search
- name: Package tutorial projects
run: npm run package:tutorials
- name: Build website
Expand Down
2 changes: 2 additions & 0 deletions .github/workflows/gh-pages-deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ jobs:
run: npm run test:tutorials
- name: Test link verification
run: npm run test:links
- name: Test search links and DocSearch fixes
run: npm run test:search
- name: Package tutorial projects
run: npm run package:tutorials
- name: Restore original video publication dates
Expand Down
35 changes: 35 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,38 @@ Keep verification code in JavaScript. For video or implementation changes, follo
the [tutorial release checks](README.md#tutorial-release-checks) and the visual
checks in the contributor notes. For notes-only edits, review links and the diff;
a website rebuild is unnecessary.

## Package upgrades and DocSearch maintenance

Before preparing a release, maintaining dependencies, or changing search/Ask AI,
check the live npm registry and official release notes for newer stable DocSearch
and Docusaurus versions. Compare them with `package.json`, `package-lock.json`,
and the upstream version recorded in any vendored package. Do not assume the
installed version or a cached search result is the latest release. For DocSearch:

```sh
npm view @docsearch/react dist-tags --json
```

While `@docsearch/react` uses a local `file:` dependency, ordinary `npm update`
will not bring Algolia's changes into that package. Follow the
[DocSearch maintenance notes](vendor/docsearch-react/README.md) when upgrading:

- Check whether the official release fixes encoded URLs, the Sidepanel's
accessible name (including its header translations), and linked-image Markdown
rendering. Verify the behavior with the regression cases; keep unsafe URL
scheme rejection and HTML escaping intact.
- If all three fixes are included, return to the official package and retire the
custom build and override. Update packaging-specific tests while retaining
the behavior checks.
- If a fix is still missing, update the custom build to the newer compatible
upstream release and retain only the fixes still needed. Refresh its source,
provenance, reviewed diff, version, packaged artifact, and lockfile together.

Keep related DocSearch packages compatible and run the
[search checks](README.md#search-and-ask-ai-checks), production build, and the
visual checks in the maintenance notes before releasing an upgrade. Record the
check date, current and latest upstream versions, and the upgrade outcome or
reason for deferral in the maintenance notes or release handoff. These checks
require a contributor to run them; this note does not install an automatic
release monitor.
15 changes: 14 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ CC BY License Copyright (c) 2022-present, core.ai

# Website

This website is built using [Docusaurus 2](https://docusaurus.io/), a modern
This website is built using [Docusaurus](https://docusaurus.io/), a modern
static website generator.

### Installation
Expand Down Expand Up @@ -49,6 +49,19 @@ External site availability and temporary server errors still need live monitorin
Run `npm run test:links` to test the checker. After a direct
`npm run docusaurus -- build`, run `npm run verify:links` separately.

### Search and Ask AI checks

Run `npm run test:search` before releasing search changes. The JavaScript tests
cover edition-specific links, crawler extraction, and the maintained DocSearch
package. Normal builds also run `npm run verify:search` to check the search page's
robots tag and tab metadata in the generated HTML. Run it separately after a
direct `npm run docusaurus -- build`.

See [search configuration](config/search/README.md) for the supported Algolia
settings, agent instructions, deployment and recrawl order, and query checks.
The reviewed DocSearch source dependency has its own
[provenance, rebuild instructions, and removal criteria](vendor/docsearch-react/README.md).

### Tutorial release checks

Before adding or changing a video, read the
Expand Down
356 changes: 356 additions & 0 deletions config/search/README.md

Large diffs are not rendered by default.

38 changes: 38 additions & 0 deletions config/search/agent-instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
You help people use Phoenix Code, the code editor for developers, designers, and students. The documentation is at https://docs.phcode.dev and in the `markdown-index` search index.

## Follow the user's goal

- Interpret any understandable request using its meaning and the conversation, including commands, fragments, spelling mistakes, pasted code, and errors. There is no fixed list of recognized questions or supported tasks. Do not steer an unfamiliar request toward a familiar tutorial.
- Carry forward relevant context, edition, and platform choices. Respect corrections and topic changes. Continue from steps the user has completed rather than restarting. Do not infer completed setup merely because the request is short.
- If a missing choice changes the procedure, ask a focused clarification or state a reasonable assumption explicitly. A retrieved example does not establish the user's file type or goal. Never claim to perform actions on the user's computer.

## Retrieve the right evidence

- Search `markdown-index` before making Phoenix Code-specific claims. A documented task is in scope regardless of feature, language, tool, or wording. Do not declare it unsupported without checking.
- 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.
- 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.

## 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.
- 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.
- For code, label the code fence with its language. Identify the file and insertion or replacement location when relevant, give a usable example, explain values to change, and say how to run or check it.
- Cite the guide beside the instructions. Essential steps must remain in the answer; optional detail, practice projects, and videos can stay in linked sources.

## Illustrate visual workflows

- 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.
- Use only retrieved image URLs. Resolve a root-relative source image against https://docs.phcode.dev and preserve its path, encoding, query parameters, and fragment. Use absolute HTTPS URLs for images and full-size links. When embedded image data has a linked image file, use that file; never output `data:` or `blob:` content.

## Links and language

- Preserve source paths, encoding, query parameters, and fragments, including edition-tab parameters. For documentation on docs.phcode.dev, use the exact root-relative path; for images and external references, use full HTTPS URLs. Do not invent filenames or section anchors.
- Use the user's language where practical, preserving actual control labels and code identifiers. Write plainly, with concise sentences and enough steps to finish the task. Avoid praise, filler, scripted introductions, generic closing questions, and unnecessary repeated summaries.
14 changes: 14 additions & 0 deletions config/search/evaluation.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
[
{"query":"text color","expectedPath":"/docs/Pro%20Features/styles-bar#text-color","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},
{"query":"run python","expectedPath":"/docs/tutorials/run-python","maxRank":3},
{"query":"image next to text","expectedPath":"/docs/tutorials/image-text-layout","maxRank":3},
{"query":"copy your picture","expectedPath":"/docs/tutorials/add-images?edition=community#copy-your-picture","maxRank":3},
{"query":"png to pdf quality","expectedPath":"/blog/how-to-convert-png-to-pdf-without-losing-quality","maxRank":3},
{"query":"png to pdf free online","expectedPath":"/blog/how-to-convert-png-to-pdf-free-online","maxRank":3},
{"query":"Phoenix Code 5.5","expectedPath":"/blog/release-5.5","maxRank":3},
{"query":"getCandidateFiles","expectedPath":"/api/API-Reference/search/FindInFiles#getcandidatefilesscope--promise","maxRank":3},
{"query":"CommandManager","expectedPath":"/api/API-Reference/command/CommandManager","maxRank":3}
]
Loading
Loading