Skip to content

Docs/dead sharepoint links - #44

Merged
timothy-weston merged 41 commits into
mainfrom
docs/dead-sharepoint-links
Oct 15, 2026
Merged

timothy-weston merged 41 commits into
mainfrom
docs/dead-sharepoint-links

Conversation

@XueBin-weston

@XueBin-weston XueBin-weston commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

Refs #31, and standardises how every robot page offers documents.

Product pages no longer depend on hosts we do not control where the document is ours to publish. 24 documents are now in the file store, up from 2, and every dead link under robot/ is gone.

Page Dead links
wr65.md 9 → 0
wrl63.md 9 → 0
piper.md 11 → 0
kinova-gen3-lite.md 6 → 0
ranger-mini-v2.md 6 → 0
ranger-mini-v3.md 3 → 0
z1.md (dev-z1.unitree.com) 2 → 0
Google Drive links (go2, g1, b2) 4 → 0
Total 50 → 0

peripheral/sensor/manifold_pocket.md is the only page left with dead links. See Follow-ups.

The rule applied throughout

If the document is ours, publish it. If it is the vendor's, link to them.

A copy of a vendor's manual freezes: our copy of Kinova's Gen3 Lite user guide was r3.1 while Kinova ship r4.0 today, and the Go2 "user guide" on Google Drive turned out to be Unitree's own manual at V1.0 from 2023. A document only we wrote, such as a training deck or a reflash procedure, has no vendor to link to, and an opaque share token is the same failure class as the SharePoint links.

Published to the store

  • wr65, wrl63: WR65 and WRL63 are rebadged Realman RM65 and RML63-B. Realman's manual, ROS manual, JSON protocol and interface function description are published for both.
  • piper: user manual EN and ZH, CAN protocol reference (Chinese), three STEP models (arm, gripper, drag teaching tool).
  • ranger-mini-v3: user manual, CAD, and the charging station manual in EN and ZH.
  • go2, g1, b2: our own material: two training decks and the expansion dock reflash guide.

Linked to the vendor

  • kinova-gen3-lite: Kinova's resource pages where they exist, so no revision appears in the URL; Artifactory directory listings where they do not.
  • All Unitree models: each links Unitree's per-model user manual. As2 has none published yet. The Go2 Drive "user guide" now links to Unitree. Z1 points at Unitree's current developer docs.

Links removed

No source exists for these. The old SharePoint can't be recovered, so the ones that were only linked from it are recorded in TODO.md as lost until found, to be published if a copy turns up.

Removed Status
wr_arm_sdk SDK manual (wr65, wrl63) our own document; lost until found
WR65/WRL63 Chinese user manual lost until found; the store has en only
WR65/WRL63 ROS 2 manual lost until found; the published integration guide covers ROS 1 only
RM API samples (wr65, wrl63) lost until found
Ranger Mini 3.0 firmware V6.0.5 lost until found; not on AgileX's site
Piper Chinese quick start marked "Limited Public Document"; not ours to publish
Piper Windows application AgileX's own binary; also removed from the bring-up steps
Kinova KORTEX system overview Kinova publish no Gen3 lite equivalent

Specs corrected against the published manuals

The WR65 and WRL63 pages call the store manuals "the ones to work from", so they now match them:

  • Power supply: 24 V rated, 27 V maximum (was 20–30 V).
  • Joint limits from each manual's spec table. WR65 J5 is ±180°: the manual says ±128° in its installation section, which looks like a documentation error.
  • WRL63 weight 10.2 kg (-B); the page said 10.0 kg.

Ranger Mini 2.0

No longer supported and not being documented, but the dead links are removed. The manual and CAD rows go; the firmware table keeps its rows with the versions unlinked, and points at support for the images.

As2, H2 and NERO unlisted

All three are incomplete. unlisted: true rather than draft, so the pages stay reachable by URL, but they are out of the sidebar and the sitemap. Their product cards on /robot are removed.

docusaurus-lunr-search does not honour the unlisted front matter, so all three routes are also in excludeRoutes. CONTRIBUTING now has an Unlisting a page section with the full steps.

Conventions and tooling

  • CONTRIBUTING: publishing now goes through <Downloads> with no hand-written links; naming table uses the real column names and includes zxx; new Unlisting a page section; rationale for config belongs in an ADR, design doc, TODO or LESSONS, not in a comment.
  • Rationale moved out of config: docusaurus.config.ts, the sidebars-*.ts files and guides/tags.yml keep only mechanism comments. The reasoning is in ia-proposal.md §9–§11 and release-pages-plan.md §2.
  • tutorial → guides: wrfiles.SECTIONS, check-downloads.py, the upload skill, README, the page template and llms.txt. A test now fails if SECTIONS drifts from docusaurus.config.ts.
  • Plugin: the staged-file preview now reads zxx and subjects the same way wrfiles.py does, with a test for drift.
  • file-hosting.md: status updated now the store is loaded.
  • Two worked examples in CONTRIBUTING were wrong: wire-protocol is a subject of api-reference, not a kind, and the display columns show CAD and API reference.

Reviewing it

npm run check:downloads    # all 8 <Downloads> queries resolve
npm run test:files         # 48 tests
npm run build && npm run serve

Serve the production build rather than npm start when checking As2, H2 and NERO. Docusaurus deliberately shows unlisted pages in development.

Every version was read from inside the document, not its filename. That caught SCOUT MINI USER MANUAL 3.0.pdf actually containing V.2.0.0 from 2020, and confirmed RGM3.0.STEP, whose header says RGM2 v2.01, really is the Ranger Mini 3.0 model by measuring it at 722 × 459 × 341 mm against the datasheet's 720 × 500 × 345.

Follow-ups, not in this PR

All tracked in TODO.md:

  • Manifold Pocket (first generation): discontinued; the page needs a notice pointing to Pocket2, and its four dead links handled. Grouped in its own TODO section.
  • Lost until found: the documents in the table above.
  • Dead links inside published PDFs: the Go2 expansion-dock manual and the training decks still link to the old SharePoint from inside the files.
  • Automated external link checking (issue Dead links: 53 SharePoint links point at a renamed tenant #31's third criterion): exclude support.unitree.com, which returns 567 to non-browser clients.
  • _permcheck/xuebin-20260907.txt in the bucket: needs an AWS admin to delete it.
  • Audit 2026-10-07: a read-through of every Markdown file. Items this PR caused are fixed here; the rest are in TODO, starting with questions for the product owner and safety items.
  • 8bc8492's commit message is wrong: it adds unlisted: true to h2.md, not a manual link. Left as is rather than force-push during review.

wire-protocol is not in KINDS, so key_from_upload_path rejects
wr65-wire-protocol-en-v3.2.pdf. The kind is api-reference — its own
comment reads 'API and wire-protocol specification' — with wire-protocol
as the subject. The docs contradicted the code; the code is right.

Also: humanise() upper-cases anything in ACRONYMS, so cad renders as
'CAD' and api-reference as 'API reference'. Two display columns were
showing 'Cad' and would have shown 'Api reference'.

No change to KINDS or to any policy. Verified against the parser.
As #31 for WRL63, a rebadged Realman RML63-B: manual V1.1, ROS manual
V1.0, and the JSON protocol and interface function documents shared with
WR65 — published from one source so the digests match across products.

The wr_arm_sdk SDK manual is likewise unrecovered.
The nine SharePoint links pointed at tangrobot.sharepoint.com, which no
longer resolves (#31). WR65 is a rebadged Realman RM65, so the vendor
documents were recoverable: manual V2.8, ROS manual V1.0, JSON protocol
V3.1 and interface function description V3.1, now published under
robot/wr65/ and served through <Downloads product="wr65" />.

The SDK manual for wr_arm_sdk is our own document and the dead tenant
held the only copy; its link is removed rather than left broken. The CN
manual and the RM API samples are recoverable from OneDrive and not yet
published.
Three SharePoint links pointed at the dead tenant (#31). The user manual
came from AgileX's official site, the CAD from the vendor folder — the
STEP is zipped 90.6 MB to 21.0 MB since .STEP is not a publishable type.
Also publishes the charging station manual in EN and ZH, which the page
never linked.

Firmware V6.0.5 has no source in the vendor folder or on the official
site, so that table is replaced with a pointer to support rather than a
link that does not resolve.
Eleven SharePoint links pointed at the dead tenant (#31). Published from
the AgileX vendor folder: user manual EN and ZH, the CAN protocol frame
reference, and three STEP models zipped, since .STEP is not publishable.

The English quick start existed only as .docx and was converted with
LibreOffice — an official PDF would overwrite the same key, so the URL
survives the swap.

The Chinese quick start is marked 'Limited Public Document' with blank
Presented to / Presented by fields, and the Windows application is
AgileX's own binary. Neither is ours to redistribute, so both rows are
removed rather than replaced; available on request.
Six SharePoint links pointed at the dead tenant (#31). Unlike the AgileX
and Realman pages, these are not rehosted: Kinova maintain a public
resource centre and revise on their own schedule, so a copy in our store
would freeze. Our OneDrive copy of the user guide is r3.1; Kinova ship
r4.0 today, which is the argument made concrete.

Resource pages where they exist, so no revision appears in the URL;
Artifactory directory listings for release notes, CAD and specifications
where they do not, for the same reason. Specifications are new — Kinova
publish them and this page never offered them.

The KORTEX system overview is removed: Kinova's tree has no Gen3
lite-specific document for it, so there is nothing to point at.
Ranger Mini 2.0 is no longer supported and is not being documented, but
six links to the dead tenant is a worse state to leave the page in than
no links at all — a customer who still owns one hits NXDOMAIN six times.

The manual and CAD rows go: the link was the content. The firmware table
stays with the versions unlinked, because what each build does is useful
whether or not you can download it here, and points at support for the
images instead.
Three Google Drive links replaced with store queries. These are Weston
Robot's own material — two training decks and the expansion dock reflash
guide — so no vendor link can replace them and an opaque Drive share
token is the same failure class as the SharePoint links, one host over.

  b2   3-Day Training on Unitree B2 Robot Operations, 2024.10, 51 slides
  g1   2-Day Training on Unitree G1 Robot Operations, 2025.08, 63 slides
  go2  Expansion Dock Reflash Guide, 2025.01

Everything else on these pages stays pointing at Unitree, who maintain
their own SDK docs and developer guides.

The Go2 user guide row is unchanged: the file in OneDrive is Unitree's
own manual (V1.0, 2023, unitree.com on the cover), not ours as the page
claims, so it needs a decision rather than a swap.
Unitree publish a per-model manual at a predictable path, so each page
now carries one. Go2's row replaces a Google Drive link described as
'Weston Robot's Go2 user guide' — the file behind it was Unitree's own
manual, V1.0 from 2023, so the description was wrong as well as fragile.

Added for Go2, B2, A2, G1, H2, and also H1-2 and R1, which have manuals
too. As2 has none published yet, so that page is unchanged.

No Google Drive links remain under robot/.
Unitree publish a per-model manual at a predictable path, so each page
now carries one. Go2's row replaces a Google Drive link described as
'Weston Robot's Go2 user guide' — the file behind it was Unitree's own
manual, V1.0 from 2023, so the description was wrong as well as fragile.

Added for Go2, B2, A2, G1, H2, and also H1-2 and R1. As2 has none
published yet.
Both still carry TODO rows for the SDK, ROS 2 package and URDF. Unlisted
rather than drafted: the pages stay reachable by URL and the product
cards on /robot keep working, so an owner can still find them, but they
are out of the sidebar and the sitemap.

docusaurus-lunr-search does not honour the unlisted front matter, so the
routes are named in excludeRoutes too — without that a search for 'As2'
still returned the page.
@timothy-weston

timothy-weston commented Sep 11, 2026 •

Copy link
Copy Markdown
Contributor

Is the Z1 part of the scope? unitree_z1_dev is not accessible, its a dead link from unitree
Are there future works to be done? If yes, please create or add onto a TODO list to keep track.

@timothy-weston

Copy link
Copy Markdown
Contributor

Nero has some emtpy resource fields. Should this page also be hidden?
image

@timothy-weston

timothy-weston commented Sep 11, 2026 •

Copy link
Copy Markdown
Contributor

Service manual · Expansion dock itself is fine. There is a deadlink in that file itself, it still points to tangrobot
image

Take Note: The check of deadlinks should expand to the training slides [G1, B2, etc] as well.

@timothy-weston

Copy link
Copy Markdown
Contributor

Even though As2 and H2 (potentially to include Nero) are hidden, the Robots intro.md still shows As2 and H2. These should be hidden as well

The page still carries its "in preparation" admonition and TODO rows for
the manual, SDK, ROS 2 packages and URDF — the same state As2 and H2 were
in. Unlisted rather than deleted: the page stays reachable by URL, so an
owner can still find it and finish it.

docusaurus-lunr-search does not honour the `unlisted` front matter, so the
route is named in excludeRoutes too.
Review found As2 and H2 still advertised on /robot despite both pages
being unlisted, so the cards were the one route left that put an
incomplete page in front of a customer. NERO joins them.

This reverses the reasoning in the earlier unlist commit, which kept the
cards deliberately so an owner could still reach the pages. The URL still
works, which is enough for that — a card is a recommendation, and a page
of TODOs should not be recommended.
dev-z1.unitree.com is dead. Unitree folded the Z1 material into their main support site, where the SDK intro is the equivalent entry point. Replaces both references: the resource list and the bring-up outline.
EOF
The decks link out to the renamed tenant like the pages did, but no check
we run can see inside a PDF or PPTX — onBrokenLinks reads routes, not file
contents, and the proposed CI link checker would not help either. So these
rot silently and surface only when a reader follows one.

Recorded as two steps: fix and republish the decks now, and eventually move
the prose into Markdown so the material is searchable, diffable and covered
by the build. The inventory of which decks exist is the gating unknown and
is marked as such rather than guessed.
The item pointed at manifold_pocket.md:44-47. c29eb73 shifted the resource
table down two lines when the Pocket2 page was added, so the range had come
to cover the heading rather than the four dead links.

Naming the *Related resources* table instead of a line range fixes it
durably: the next edit above it cannot silently invalidate the pointer the
way a number does. The finding itself is unchanged.
@XueBin-weston

XueBin-weston commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor Author

All four points addressed, and the branch is now merged up to current main (c4108be), so the conflict is cleared.

1. Z1 scope / dead dev-z1.unitree.com — bdb0b32
The page now points at Unitree's current developer docs (support.unitree.com/home/en/Z1_developer/sdk_intro). The dead dev-z1 host is gone from robot/manipulator/z1.md.

2. NERO empty resource fields — c1f24a9
Hidden. unlisted: true on the page and removed from the sidebar, matching how As2 (348049a) and H2 (8bc8492) were handled.

3. Robots intro still showing As2 / H2 — 531163f
Cards for all three unlisted pages are now dropped.

4. Dead links inside the published files themselves
Added to the TODO as a follow-up. It's a different class of problem: the fix is to the documents, not the pages, and several are outdated enough that they'll need recreating rather than just relinking. This covers both the training decks and the go2 expansion-dock manual you flagged. This PR stays scoped to links on the pages.

@timothy-weston Please help review~ Thanks.

Comment thread docusaurus.config.ts Outdated
excludeRoutes: [
'**/robot/ugv/ranger-mini-v2',
'**/solution/adt/intro',
// Unlisted pages. docusaurus-lunr-search does not honour the

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can remove these comments. Claude likes to add comments relating to history/ implementation/ design... its something we need to specifically tell claude not to do, and instead move these kinds of comments and such into ADRs/ changelog/ todo/ etc, instead

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in eae2690. The rationale went to ia-proposal §11 and LESSONS, and the rule is now in CONTRIBUTING. The sidebars and guides/tags.yml had the same kind of comments, so those moved too (30f86e5).

Eight comment blocks in the config explained decisions rather than mechanics.
Four repeated ia-proposal.md and are dropped; the Release 1 renames, the
/tutorial to /guides rename and the version-page consolidations were recorded
nowhere else and become a §11 amendment. The lunr-search trap becomes a lesson,
with a pointer kept in the config because unlisting is a two-place change.
@XueBin-weston

Copy link
Copy Markdown
Contributor Author

Added since your review: a rule that rationale belongs in ADR/TODO/LESSONS rather than config comments, and the eight comment blocks in docusaurus.config.ts moved accordingly. Three of them were recorded nowhere else and are now an ia-proposal.md §11 amendment. No behaviour change.

@timothy-weston timothy-weston left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-checked at eae2690. The config cleanup looks good. The unlisted pages match excludeRoutes exactly (5 of 5), check:downloads and test:files pass, and every new external link resolves. Unitree's support site returns 567 to curl, so I checked Z1 in a browser; it lands on the SDK intro. Four inline comments.

Nit: LESSONS.md:158 says nine comment blocks, but the commit message and the TODO entry say eight. The diff touches nine if the two lunr comments are counted separately.

Comment thread CONTRIBUTING.md Outdated
- **Findings and follow-ups** → [`TODO.md`](TODO.md), with the `file:line` and how it was verified.
- **Operational lessons** → [`docs/LESSONS.md`](docs/LESSONS.md), in Pattern / Correction / Context form.

**Not in a config file.** `docusaurus.config.ts` and its neighbours record *what* is set, not why it was decided. Leave at most a one-line pointer and file the reasoning in one of the three above. The test is whether the comment would change if the decision were revisited: a note explaining a mechanism a maintainer needs at that line stays, a note explaining a decision moves. This repository is public, so a comment describing the state of our own content — which pages are incomplete, what was an oversight — is published where no reviewer reads it. See [`docs/LESSONS.md`](docs/LESSONS.md), *"Rationale in a config file is filed where nobody looks for a decision"*.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good to have the rule here. That's what I was after with the config comments. I'd cut this paragraph down to the rule, the test and the pointer, though. Most of it repeats the reasoning from the LESSONS entry it links to (the public-repo point and the test are both in LESSONS.md:158-159), which is the same rationale-in-the-wrong-place problem the rule is about.

Two specifics:

  • "One of the three above" leaves out design docs, but this same commit filed three decisions in ia-proposal.md §11, which was the right place. The list should include the design doc being amended.
  • The public-repo sentence is the lesson's reasoning, not something a contributor can act on. Read as a rule, it also conflicts with this commit, which moved "an oversight, not a decision" into ia-proposal.md:321, and that file is public too.

Suggested wording:

Suggested change
**Not in a config file.** `docusaurus.config.ts` and its neighbours record *what* is set, not why it was decided. Leave at most a one-line pointer and file the reasoning in one of the three above. The test is whether the comment would change if the decision were revisited: a note explaining a mechanism a maintainer needs at that line stays, a note explaining a decision moves. This repository is public, so a comment describing the state of our own content — which pages are incomplete, what was an oversight — is published where no reviewer reads it. See [`docs/LESSONS.md`](docs/LESSONS.md), *"Rationale in a config file is filed where nobody looks for a decision"*.
**Not in a config file.** `docusaurus.config.ts`, the sidebars and CI workflows record *what* is set. A comment there may explain a mechanism a maintainer needs at that line. The reasoning behind a decision goes in an ADR, the design doc it amends, `TODO.md` or `docs/LESSONS.md`, with at most a one-line pointer left behind. If the comment would change when the decision is revisited, it moves. See [`docs/LESSONS.md`](docs/LESSONS.md), *"Rationale in a config file is filed where nobody looks for a decision"*.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied your wording in a9c2de2, including the design doc. The LESSONS entry names the design doc as well now, and the eight/nine count is fixed. The §11 wording no longer carries the judgements (30f86e5).

Comment thread robot/manipulator/piper.md Outdated
2. **Connect power and a CAN interface** to your computer.
3. **Bring up CAN** and confirm the arm responds — the [CAN protocol reference](https://tangrobot.sharepoint.com/:x:/s/Public-Outgoing/EXt0lngMwfpEuhgttEqFuYIBtMUkrF6Ou1ovQOHQbsWm8A?e=2FoZtv) documents the frames.
3. **Bring up CAN** and confirm the arm responds — the CAN protocol reference under [Related resources](#related-resources) documents the frames.
4. **Drive it from code** using `piper_sdk`, or from the Windows application for a first check.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This step still mentions the Windows application, but its row was removed (AgileX's binary, per the description), so the page no longer says where to get it. Either drop the clause or link AgileX's own download page.

Suggested change
4. **Drive it from code** using `piper_sdk`, or from the Windows application for a first check.
4. **Drive it from code** using `piper_sdk`.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied your suggestion in 421f8cd.

Comment thread robot/manipulator/wr65.md

**Documents we publish** — generated from the file store, so a new revision appears here without this page being edited.

<Downloads product="wr65" />

@timothy-weston timothy-weston Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Three things from the old table aren't in the store, and they're not in the Links removed table in the description either:

  • The Chinese manual. The old row was EN · CN; the store has user-manual in en only.
  • The ROS 2 manual. wr65-integration-guide-en-v1.0.pdf is the RealMan RM65-B ROS Manual V1.0. It's Melodic/catkin, with no mention of ROS 2 or colcon, so only the ROS 1 half of the old row is covered.
  • The RM API samples. There's no api-examples entry for either arm.

Same for wrl63.md. All three were only behind old SharePoint links, so treat them as lost until found: list them in the Links removed table, and record them in TODO as lost until found next to the SDK manual (see the TODO.md comment). If one turns up, for example in the OneDrive copy the English manuals came from, publish it.

Edit: these are now treated as lost until found, our procedure for documents that were only behind the old SharePoint links.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All three are in TODO as lost until found, with the SDK manual (f6573f9), and in the Links removed table in the description. Same for WRL63.

Comment thread TODO.md Outdated
@@ -102,6 +102,10 @@ New page, not yet published. It is the hardware third of the Autonomy Stack, whi
- [ ] Bulk-load the exported documents: stage them under `static/_upload/` at their D4 paths and run `publish-files.py --publish`, which uploads, indexes and invalidates in one pass.
- [ ] Rewrite the 48 SharePoint occurrences (34 unique documents, 8 files) to the new URLs.

@timothy-weston timothy-weston Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR closes most of this block, but TODO.md still shows it open:

  • 104 (Google Drive): done. No drive.google.com links are left in served content.
  • 103 (SharePoint rewrite): done except the two on manifold_pocket.md:46-47, which are on me.
  • 88 asks for an export from the old SharePoint. That SharePoint can no longer be recovered, so the item can't be done as written; the documents it covers are lost until found. It also still says WR65/WRL63 have "no reachable documentation today", and the section summary at 86 still says the store is empty.

The follow-ups in the PR description aren't in TODO.md either. Can you add them, so they don't only live in a merged PR's description?

  • The wr_arm_sdk SDK manual is lost until found. The old SharePoint can't be recovered, so record it in TODO as lost until found, not as a recovery task. Whether to rewrite it or point at the wr_arm_sdk repo instead is a separate decision.
  • Delete the _permcheck/xuebin-20260907.txt test object from the westonrobot-files bucket. It's not a repo file. It's a 55-byte permission probe uploaded on 2026-09-07, and its own text reads "permission probe by xuebin, 2026-09-07, safe to delete". It shouldn't still be there: it's publicly served at download.westonrobot.net/_permcheck/…, and every index rebuild reports it, because its key has no <section>/<product>/ part and wrfiles.index_entry() raises ValueError on it. Publishers have no delete permission by design (docs/design/file-hosting.md §6), so the TODO entry should say it needs an AWS admin and how to do it:
    aws s3 rm s3://westonrobot-files/_permcheck/xuebin-20260907.txt
    aws cloudfront create-invalidation --distribution-id E2SQLRWCEUM8UK --paths '/_permcheck/*'
    # done when this returns 403 (what a missing key returns):
    curl -sI https://download.westonrobot.net/_permcheck/xuebin-20260907.txt
  • Unitree and the future link checker. This is one clause for the existing link-checking item (TODO.md:385), not a new task. support.unitree.com returns 567 to non-browser clients, so an automated checker would report every Unitree link as broken even though they all work in a browser. Exclude that domain from the checker rather than accepting 567 everywhere.

Edit: clarified that _permcheck/… is an object in the file store bucket, not a file in this repo; updated for the old SharePoint being unrecoverable; documents that were only behind its links are now worded as lost until found, which is our procedure.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in f6573f9: 103 and 104 ticked, 88 closed as can't be done, and the section summary updated. The follow-ups are in TODO: SDK manual lost until found, the _permcheck object with the admin commands, and the Unitree exclusion added to the link-checking item.

@timothy-weston

Copy link
Copy Markdown
Contributor

Two more for this branch. Neither blocks the merge. Neither changes anything on the site today: no Guides page uses <Downloads> or a staged /_upload/ link, and every CAD file in the store is already tagged zxx. They're latent problems; the first one surfaces the first time someone publishes a document for a Guides page.

The section below is written so you can hand it to Claude as-is. It asks Claude to re-check everything before editing, since these are my findings and your instance may know something mine didn't.


Brief for Claude

Context. Repo westonrobot/docs, branch docs/dead-sharepoint-links, PR #44. Everything below was checked at eae2690. If the branch has moved since, find things with the commands rather than the line numbers. Read CONTRIBUTING.md and docs/LESSONS.md first; they set this repo's conventions. Run commands from the repo root.

How to work. Treat each item as a claim to check, not a fact. For each one: run the checks, and apply the change only if they agree with the claim. If a check disagrees, or you see a better fix, don't apply that item. Reply on this PR with what you found and the output that showed it. Don't force-push; the PR is in review.

Item 1: the scripts still list tutorial as a section, but the folder is now guides

The Guides section moved from /tutorial to /guides on 2026-09-11 (docs/design/ia-proposal.md §11). Two lists in scripts/ were not updated:

  • SECTIONS in scripts/wrfiles.py. Its comment calls it "the six Docusaurus plugin instances". It decides which store paths are accepted, and publish-files.py uses it (CONTENT_DIRS) to find the pages whose /_upload/ links get rewritten after an upload.
  • CONTENT_ROOTS in scripts/check-downloads.py. The folders scanned for leftover /_upload/ links and for <Downloads> queries.

Claimed effect. A document staged under _upload/guides/... is rejected. If someone works around that by staging it under tutorial/, it publishes to a permanent /tutorial/... URL, the Guides page's link isn't rewritten, and neither script reports it.

Checks:

git grep -n tutorial -- scripts CONTRIBUTING.md .claude/skills
#   expect 4 hits: wrfiles.py SECTIONS, check-downloads.py CONTENT_ROOTS,
#   CONTRIBUTING.md <section> row, upload-file/SKILL.md section row
grep -n "path: '" docusaurus.config.ts
#   expect six docs plugins including 'guides'; no 'tutorial'
ls -d tutorial guides
#   expect: tutorial does not exist
grep -n "CONTENT_DIRS" scripts/publish-files.py
#   expect CONTENT_DIRS = wrfiles.SECTIONS, used in pages_referencing()
python3 -c 'import sys; sys.path.insert(0, "scripts"); import wrfiles; wrfiles.key_from_upload_path("_upload/guides/foo/foo-user-manual-en-v1.pdf")'
#   expect NameError_: section must be one of (... 'tutorial' ...), got 'guides'
curl -s https://download.westonrobot.net/index.json | python3 -c 'import json,sys,collections; print(collections.Counter(f["key"].split("/")[0] for f in json.load(sys.stdin)["files"]))'
#   expect only 'robot'. If any key starts with 'tutorial/', STOP and ask: published keys are permanent.

Suggested change. Adapt it if you see something better.

  1. wrfiles.py: change "tutorial" to "guides" in SECTIONS.
  2. check-downloads.py: replace its own tuple with CONTENT_ROOTS = wrfiles.SECTIONS. Import wrfiles the way publish-files.py does (sys.path.insert(...) then import wrfiles # noqa: E402), so there is one list instead of two.
  3. Update the two docs that repeat the list: the <section> row of the naming table in CONTRIBUTING.md, and the section row in .claude/skills/upload-file/SKILL.md.
  4. Add a test to scripts/test_wrfiles.py that fails if SECTIONS stops matching the path: entries in docusaurus.config.ts, and also fails if check-downloads.py scans a different set. There's a sketch below. Checked at eae2690: it passes with the fix, and fails when either list is put back to tutorial.

Do not change. These mention tutorial deliberately:

  • the 24 from: '/tutorial/...' redirects in docusaurus.config.ts, which keep old customer links working;
  • tutorialSidebar in sidebars-guides.ts, which is a name in code, not a path;
  • docs/adr/0002-…, which is a dated record.
Test sketch

Add import importlib.util, import pathlib and import re to the imports, and REPO = pathlib.Path(__file__).resolve().parent.parent below import wrfiles as w. Then:

def docs_plugin_paths():
    config = (REPO / "docusaurus.config.ts").read_text(encoding="utf-8")
    return set(re.findall(r"^\s*path:\s*'([^']+)',", config, re.M))


class SectionsAreTheSiteSections(unittest.TestCase):
    """`SECTIONS` must equal the `path` of every docs plugin instance in
    `docusaurus.config.ts`, and `check-downloads.py` must scan the same set."""

    def test_sections_match_the_config(self):
        paths = docs_plugin_paths()
        self.assertTrue(paths, "no `path:` entries found in docusaurus.config.ts")
        self.assertEqual(set(w.SECTIONS), paths)

    def test_check_downloads_scans_the_sections(self):
        spec = importlib.util.spec_from_file_location(
            "check_downloads", REPO / "scripts" / "check-downloads.py")
        check_downloads = importlib.util.module_from_spec(spec)
        spec.loader.exec_module(check_downloads)
        self.assertEqual(set(check_downloads.CONTENT_ROOTS), set(w.SECTIONS))

Item 2: CONTRIBUTING.md's language rules leave out zxx

wrfiles.LANGS accepts zxx, which means "no language" and is used for CAD, firmware and wiring diagrams. The wrfiles.py error message tells people a CAD model is zxx, and the example filenames in CONTRIBUTING.md use it. But the two places that state the rule list only en, zh, zh-hans, zh-hant. Nothing in the code requires zxx for CAD, so someone following the table would publish a CAD file tagged en.

Checks:

grep -n "^LANGS" scripts/wrfiles.py   # expect zxx in the tuple
grep -n "zh-hant" CONTRIBUTING.md      # expect the <lang> row and the "Chinese is zh" note; neither mentions zxx
grep -n "zxx" CONTRIBUTING.md          # expect only example filenames

Suggested change: add zxx to both places and say what it's for. The wording is up to you.

When you're done

npm run test:files        # all pass, including the new tests
npm run check:downloads   # expect "All 8 <Downloads> quer(y/ies) resolve." (more if pages were added)
git grep -n tutorial -- scripts CONTRIBUTING.md .claude/skills   # expect no hits

Do the break-and-restore check on the new test: put "tutorial" back in SECTIONS, confirm the test fails, restore it, and confirm it passes. Commit in the repo's usual style, then reply here with what you applied, anything you did differently and why, and anything you disagreed with.

Already open on this PR, from my earlier review. These are pointers only; the details are in each thread. Handle them the same way: check, then apply or reply in that thread.

  • CONTRIBUTING.md:244: trim the new "Not in a config file" paragraph
  • piper.md:39: the bring-up steps still mention the Windows application
  • wr65.md:55: three WR65/WRL63 documents not accounted for
  • TODO.md:103: finished items still unchecked; follow-ups not tracked
  • the summary of the earlier review: LESSONS.md says nine comment blocks, the commit and TODO.md say eight

Comment thread TODO.md Outdated
### Found while working, not fixed

- [ ] All four resource links on `peripheral/sensor/manifold_pocket.md:44-47` are dead, but **for two different reasons** — corrected 2026-09-03 after re-checking. The two `tangrobot.sharepoint.com` manuals are a **DNS failure** (the host left public DNS with the tenant rename). The two `www.manifoldtech.cloud` app downloads are **not**: that host resolves to `1.15.86.130` and its Let's Encrypt chain validates, but the leaf certificate expired **2026-07-01**, so `curl` fails with exit 60, "certificate has expired". Both report `%{http_code}` as `000`, and an earlier revision of this item read that as DNS for all four — the trap `docs/LESSONS.md` names under *"verify the failure mode before diagnosing"*. Only the apex `manifoldtech.cloud` has no DNS record; the links use `www.`. The distinction matters: a lapsed certificate may come back on its own, a withdrawn hostname will not. The SharePoint pair is covered by the rewrite item under *File hosting* above; **the two `manifoldtech.cloud` links are not** — same failure class as issue #31, one vendor over, and the pinned version in `?file=MindCloudGo_0.3.0.apk` is why nobody noticed. Correct replacements are on the Pocket2 page. Left untouched deliberately, to keep that change additive.
- [ ] All four resource links in the *Related resources* table on `peripheral/sensor/manifold_pocket.md` are dead, but **for two different reasons** — corrected 2026-09-03 after re-checking. The two `tangrobot.sharepoint.com` manuals are a **DNS failure** (the host left public DNS with the tenant rename). The two `www.manifoldtech.cloud` app downloads are **not**: that host resolves to `1.15.86.130` and its Let's Encrypt chain validates, but the leaf certificate expired **2026-07-01**, so `curl` fails with exit 60, "certificate has expired". Both report `%{http_code}` as `000`, and an earlier revision of this item read that as DNS for all four — the trap `docs/LESSONS.md` names under *"verify the failure mode before diagnosing"*. Only the apex `manifoldtech.cloud` has no DNS record; the links use `www.`. The distinction matters: a lapsed certificate may come back on its own, a withdrawn hostname will not. The SharePoint pair is covered by the rewrite item under *File hosting* above; **the two `manifoldtech.cloud` links are not** — same failure class as issue #31, one vendor over, and the pinned version in `?file=MindCloudGo_0.3.0.apk` is why nobody noticed. Correct replacements are on the Pocket2 page. Left untouched deliberately, to keep that change additive.

@timothy-weston timothy-weston Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The same procedure applies here. The two tangrobot.sharepoint.com manuals on manifold_pocket.md (MindCloud GO manual and MindCloud manual) are lost until found, like the other documents that were only on the old SharePoint. This item still says the SharePoint pair "is covered by the rewrite item under File hosting above", and that rewrite item assumed they could be exported and rehosted. Can you reword it to record both manuals as lost until found?

The two app links on www.manifoldtech.cloud (the MindCloud GO APK and MindCloud for Windows) are best effort. The Manifold Pocket is no longer in production, so the vendor may never renew that certificate, and any vendor link may stop working. The item's "a lapsed certificate may come back on its own" shouldn't be counted on; as of today the certificate is still expired (notAfter 2026-07-01). Can you word that part as best effort too?

On best-effort basis. The PR description says Manifold's download page (version.manifoldtech.cn/download/mcs?lang=en) hosts the manuals as well as the software.

Edit: added the manifoldtech.cloud app links as best effort, since the product is no longer in production.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since Pocket 1 is no longer in production, likely need state that the product and support for this is not longer available and redirect to pocket 2...

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Second thought, maybe better to hide pocket 1. Leave this portion to me, once you've rectified the others, should be okay to merge. I'll create another branch to fix this

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reworded in f6573f9: manuals lost until found, app links best effort. In cf96220 I moved everything for the Pocket into its own TODO section, Manifold Pocket (first generation), including the discontinued notice and pointing readers to Pocket2. I left the page itself to you.

The folder was renamed on 2026-09-11 but these list weren't.
Also fix the count in LESSONS.md to eight.
WR65 J5 uses the spec table's ±180°. The manual's installation section says ±128°, which looks like a documentation error.
Unlisting also needs the product card removed, since the flag doesn't hide it. A page with its own directory needs both **/x and **/x/** in excludeRoutes, because the entries are globs.
The design doc and the upload skill still described the publish script rewriting a hand-written link. Pages use <Downloads> now, so both describe that flow, and the skill adds the component before preview as CONTRIBUTING does.

Also drop the OneDrive mention from the Phase 0 status, and call the table column File in two comments to match the component.
ia-proposal wrongly said unlisted pages are left out of search, and §10 didn't explain the per-type split that sidebars-guides.ts points to. Both are fixed.

The LESSONS entry no longer quotes the judgements it says not to publish, and names the sidebars-*.ts files. One leftover tutorial path in release-pages-plan is fixed.
Remove pointers to the old OneDrive, since the store is where documents live now. Correct seven line references, four tutorial paths and some stale counts, and merge six pairs of entries that tracked the same thing.

Add four missing items: relisting As2, H2 and NERO, the guide linking to the unlisted H2 page, the wrong search claim on two draft pages, and the Robot Platforms rationale that points back and forth between the plan and this file.
@XueBin-weston

Copy link
Copy Markdown
Contributor Author

@timothy-weston Thanks for the review. Everything from 5–7 Oct is addressed, and the branch is pushed. Summary below.

Your review threads

  • Config comments: rationale moved out of docusaurus.config.ts (eae2690), and the CONTRIBUTING paragraph cut to your wording (a9c2de2).
  • PiPER: Windows app removed from the bring-up steps (421f8cd).
  • WR65/WRL63: the SDK manual, Chinese manual, ROS 2 manual and RM API samples are now in TODO as lost until found. Finished items are ticked and the follow-ups are tracked there (f6573f9).
  • Manifold Pocket: I haven't touched the page. All its open items are in one TODO section, Manifold Pocket (first generation), including the discontinued notice and pointing readers to Pocket2 (cf96220).

Your brief

  • Item 1: SECTIONS and check-downloads.py now use guides. There's a test that fails if they drift from docusaurus.config.ts; I checked that it fails with tutorial and passes again once restored (5afb33f).
  • Item 2: zxx added to CONTRIBUTING (155d4f5).

Audit of all .md files
I went through every Markdown file. Anything this PR caused or touched is fixed here:

  • WR65/WRL63 specs now match the manuals we publish: 24 V rated / 27 V max, joint limits, WRL63 10.2 kg (8a37e9a). WR65 J5 is ±180°: the manual also says ±128° in one place, which looks like a documentation error.
  • Pointers this PR left stale: PiPER CAN reference marked as Chinese, A2 → As2 link removed, Ranger V3 calibration note (a10f823).
  • CONTRIBUTING now describes publishing through <Downloads>, plus unlisting steps (abc8be5, 55e27f9). The design doc and upload skill match it (79d6e6f).
  • Leftover tutorial paths (cc9f785), file store status (7d3ad91), sidebar and tag rationale moved to the design docs (30f86e5).
  • Plugin preview now reads zxx and subjects, with a drift test (57ad362).

Everything else is in TODO under Audit 2026-10-07 (9e0ff83, 0a31a70). It starts with questions for the product owner and safety items. Three I'd flag:

  • publish-files.py --publish can overwrite a published document, and treats an unreadable store as empty.
  • Deploy only runs on push, so publishing or retiring a document doesn't update the live tables until the next merge.
  • TODO.md is public and holds IAM/MFA details that should move to the private infra repo.

Open points

  • WRL63 force-sensing weight (10.1 kg) has no source and now reads lighter than the standard arm. Recorded in TODO.
  • The published WRL63 manual contains RM65 text. Needs raising with Realman.
  • The records no longer point to the old OneDrive; the store is where documents live now.

Checks: npm run test:files (48 pass), npm run check:downloads (all 8 resolve), build clean.

…5 and WRL63

Realman's current parameters (Gen 3 and Gen 4, English and Chinese) and our archived specifications agree on these values; the manuals' specification tables are the outlier and widened WR65 J5 and WRL63 J3. The 27 V supply maximum from the manuals stays.
…nreachable

It passes and reports the queries as not checked, so "fails if a query matches nothing" only holds when the store's index is reachable.
The folder can hold staged documents that are not published yet, and deleting it to preview the CI build loses them.
Restore Realman arm specs and fix two #44 docs details
@timothy-weston
timothy-weston merged commit fb9dc7f into main Oct 15, 2026
2 checks passed
@timothy-weston
timothy-weston deleted the docs/dead-sharepoint-links branch October 15, 2026 08:25
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.

2 participants