Skip to content

Correct three fabricated mechanisms in sweep-authored docs - #30

Merged
nahumtimerman merged 2 commits into
mainfrom
docs/fix-fabricated-mechanism-docs
Sep 10, 2026
Merged

nahumtimerman merged 2 commits into
mainfrom
docs/fix-fabricated-mechanism-docs

Conversation

@nahumtimerman

Copy link
Copy Markdown
Collaborator

Follow-up audit after the QS_ prefix error found in #29. All three of these were written during the PR #17 catch-up, by taking a changeset comment and guessing a plausible mechanism instead of reading the implementation. Each silently does nothing when a reader follows it.

1. AI Assistant placeholders

Documented Actual
Key AIChatURL AiChatUrl (product, Web.config, sample customer.config)
Missing {context}, {pageContent}

{context} is the JSON bundle of every other value — and the placeholder used by the example Quali itself ships in customer.config (perplexity.ai/search?q={context}). {pageContent} is the visible page text, whitespace-collapsed and truncated to 2000 characters.

Added both, plus:

  • a warning that either placeholder sends on-screen Portal content (resource names, addresses, attribute values) to the external chat service, where it may be logged;
  • values are URL-encoded automatically, so don't pre-encode;
  • an unknown or misspelled placeholder resolves to empty rather than erroring.

Verified against qdPortalHeader.ts and replaceNamedTokens in utilities.js — deliberately not against the AppSetting description string, which is itself stale (it omits pageContent, resourceList, resourceCount and is the kind of secondhand source that caused these bugs).

The key-name error was cosmetic rather than breaking: NameValueCollection lookup is case-insensitive, so AIChatURL did resolve. Fixed for consistency with the product.

2. AllowUnicodeForCommandContext pointed at the wrong machine

Documented as a CloudShell Server key. It's read by ScriptCommandExecutionOperation in TestShell/Runtime/Service — the Execution Server project, which owns QsExecutionServer.exe.config whose appSettings has file="customer.config". Setting it on the Quali Server has no effect. Corrected component and location; pinned the version to 2024.1.0.2669 to match What's New.

3. Docker ES attributes

Documented as one -e ATTRIBUTE_<Name>=<Value> flag per attribute. No such prefix is handled anywhere in the product. es_start.sh reads a single ES_ATTRIBUTES variable containing a JSON object and forwards it as /a: to QsExecutionServerConsoleConfig. Rewrote against the entrypoint and Program.cs, and documented that names may contain spaces, the variable is optional, and attributes apply at first registration.

Audit scope

Extracted every <add key="..."> in the configuration-options tree — 186 keys — and checked each against the product source. All 186 exist; there are no further invented key names. The 2026.1 / 2024.1 version claims on all three items above were verified against the release branches and are correct.

I also corrected a memory note of my own that turned out to be an unverified inference: I had been treating AppSettingVisibility.Support as a gate on customer documentation. The enum is declared // used by QsBuild in Reflection, has no consumer in the workspace, and correlates poorly with reality — AiChatUrl is Support yet ships with a sample value in customer.config, while MoreShellsUrl (a community link) is Customer. Nothing was removed from the docs on the strength of it.

Verification

npx docusaurus build passes; the 3 broken links reported are pre-existing (intro/features/abstract-resources). Diff is pure LF.

🤖 Generated with Claude Code

nahumtimerman and others added 2 commits September 10, 2026 11:06
Follow-up audit after the QS_ prefix error in #29. All three of these
were written during the PR #17 catch-up from a changeset comment plus a
plausible guess at the mechanism, without reading the implementation.
Each one silently does nothing when followed.

- AI Assistant placeholders: the key was documented as `AIChatURL`; the
  product, the shipped Web.config and the sample customer.config all use
  `AiChatUrl`. (AppSettings lookup is case-insensitive, so this one was
  cosmetic rather than broken.) Two placeholders were missing entirely:
  `{context}`, the JSON bundle of every other value - and the one used
  by the example Quali ships in customer.config - and `{pageContent}`,
  the visible page text collapsed and truncated to 2000 characters.
  Added both, plus a warning that either one sends on-screen Portal
  content to the external service, and notes that values are
  URL-encoded automatically and unknown placeholders resolve to empty
  rather than erroring. Verified against qdPortalHeader.ts and
  utilities.js replaceNamedTokens, not the AppSetting description string
  (which is itself stale - it omits pageContent, resourceList and
  resourceCount).

- AllowUnicodeForCommandContext was documented as a CloudShell Server
  key. It is read by ScriptCommandExecutionOperation in
  TestShell/Runtime/Service, which is the Execution Server project - it
  owns QsExecutionServer.exe.config, whose appSettings section has
  file="customer.config". Setting it on the Quali Server has no effect.
  Corrected the component and location, and pinned the version to
  2024.1.0.2669 to match What's New.

- Docker Execution Server attributes were documented as one `-e
  ATTRIBUTE_<Name>=<Value>` flag per attribute. No such prefix is
  handled anywhere; es_start.sh reads a single ES_ATTRIBUTES variable
  containing a JSON object and forwards it as /a: to
  QsExecutionServerConsoleConfig. Rewrote the section against the
  entrypoint and Program.cs.

Also audited every config key in the configuration-options tree - all
186 exist in the product, so there are no further invented key names.
The "2026.1" and "2024.1" version claims on these three were checked
against the release branches and are correct.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@nahumtimerman
nahumtimerman merged commit dcc4349 into main Sep 10, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant