Edison Jwa
bba6273af7
- Move ASPICE docs to chanoraapp/docs submodule at docs/ - Move development docs to dev-docs/ (superpowers, offline-knowledge, impl-mapping) - Add AGENTS.md with project conventions for AI agents - Add impl-mapping.md (SAD component → source file mapping) - Archive completed plans to dev-docs/superpowers/plans/_archived/ - Remove AGENTS.md from .gitignore (now tracked)
194 lines
9.6 KiB
Markdown
194 lines
9.6 KiB
Markdown
# External Documentation Review
|
||
|
||
> **Reviewer**: OpenCode (automated)
|
||
> **Date**: 2026-06-13
|
||
> **Files reviewed**:
|
||
> - `docs/offline-knowledge/external/teaspeak-overview.md`
|
||
> - `docs/offline-knowledge/external/respeak-overview.md`
|
||
> - `docs/offline-knowledge/external/yatqa-en.md`
|
||
> - `docs/offline-knowledge/external/yatqa-de.md`
|
||
|
||
---
|
||
|
||
## 1. teaspeak-overview.md
|
||
|
||
### Accuracy
|
||
|
||
| Claim | Verdict | Notes |
|
||
|-------|---------|-------|
|
||
| Repo at `git.did.science/TeaSpeak` | ✅ Confirmed | GitLab instance accessible |
|
||
| TeaSpeak-Client: 329 commits, created May 2020 | ✅ Confirmed | GitLab shows 329 commits, created May 19, 2020 |
|
||
| TeaSpeakLibrary: 208 commits, created May 2020 | ✅ Confirmed | GitLab shows 208 commits, created May 10, 2020 |
|
||
| Developer: WolverinDEV / TeaSpeak | ⚠️ Unverifiable | Cannot confirm from public repo metadata alone |
|
||
| Electron 8.5.5, TypeScript 3.9 | ⚠️ Unverifiable | Repo not fully cloned; cannot read package.json |
|
||
| C++20 for TeaSpeakLibrary | ⚠️ Unverifiable | Cannot read CMakeLists.txt without full clone |
|
||
|
||
### Missing Items
|
||
|
||
- **License not mentioned.** The doc does not state the project's license. If the license is known, it should be included for completeness.
|
||
- **No mention of project status/activity.** Last commit date, maintenance status, or whether the project is actively developed would be useful context.
|
||
- **No mention of WebRTC.** The client tree includes `imports/shared-app/connection/rtc/` (WebRTC-related types) and `native/serverconnection/src/connection/` has video connection support, but the doc doesn't discuss WebRTC integration or video capabilities in depth.
|
||
|
||
### Factual Errors
|
||
|
||
None found. All verifiable claims (commit counts, creation dates, repo URL, directory structure) match the source.
|
||
|
||
### Structure
|
||
|
||
Well-organized with clear sections for Architecture, Features, Technology Stack, Protocol/API, Build, and Key Concepts. The directory tree diagrams are useful. The separation of Client vs Library technology tables is good.
|
||
|
||
### Verdict: **Good** — Accurate where verifiable. Add license info and project status.
|
||
|
||
---
|
||
|
||
## 2. respeak-overview.md
|
||
|
||
### Accuracy
|
||
|
||
| Claim | Verdict | Notes |
|
||
|-------|---------|-------|
|
||
| License: MIT OR Apache-2.0 | ✅ Confirmed | `Cargo.toml` and LICENSE files confirm |
|
||
| tsclientlib 0.2.0, tsproto 0.2.0 | ✅ Confirmed | From `Cargo.toml` files |
|
||
| Crate versions (ts-bookkeeping 0.1.x, tsproto-packets 0.1.x, tsproto-types 0.1.x) | ✅ Confirmed | Matches Cargo.toml versions |
|
||
| Features table (audio, unstable, default-tls, bundled, static-link, audiopus-unstable) | ✅ Confirmed | Exact match in `tsclientlib/Cargo.toml` |
|
||
| Dependencies (hickory-proto, hickory-resolver, reqwest, audiopus, tokio) | ✅ Confirmed | All present in Cargo.toml |
|
||
| Source file listings | ✅ Confirmed | All files exist in repo structure |
|
||
| Examples (simple.rs, audio.rs, etc.) | ✅ Confirmed | All present in `tsclientlib/examples/` |
|
||
| Performance: 199ms connection, 189µs message | ✅ Confirmed | Exact match in README |
|
||
| Qint reference | ✅ Confirmed | Mentioned in README |
|
||
| SimpleBot reference | ✅ Confirmed | Mentioned in README |
|
||
| "Not official TeamSpeak project" / "will not publish server related code" | ✅ Confirmed | Exact language in README |
|
||
| Chanora rev `04aa2491` | ✅ Confirmed | Both `chanora_protocol/Cargo.toml` and `chanora_audio/Cargo.toml` pin to this rev |
|
||
| Four crates used (tsclientlib, tsproto-packets, tsproto-types, ts-bookkeeping) | ✅ Confirmed | Listed in `chanora_protocol/Cargo.toml` |
|
||
| Architectural constraint SAD-067 / SysDes-011 / SysDes-029 | ✅ Confirmed | `chanora_protocol` description and `docs/sysdes.md` reference these |
|
||
| Patched fork for P-256 short coordinate padding | ✅ Confirmed | `[patch]` section in workspace `Cargo.toml` |
|
||
|
||
### Factual Errors — Encryption Algorithm Section
|
||
|
||
**Error 1: Key derivation description is misleading.**
|
||
|
||
The doc states:
|
||
> 1. **Key derivation**: `SHA-256(packet_type || generation_id || shared_iv)` → 16-byte key + 16-byte nonce
|
||
|
||
The actual code in `tsproto/src/algorithms.rs` (`create_key_nonce`) constructs a 70-byte buffer:
|
||
```
|
||
temp[0] = 0x30 or 0x31 (depending on client_id presence)
|
||
temp[1] = packet_type
|
||
temp[2..6] = generation_id (big-endian)
|
||
temp[6..] = shared_iv (64 bytes)
|
||
```
|
||
Then `keynonce = SHA-256(temp)`, split into 16-byte key + 16-byte nonce.
|
||
|
||
The doc's notation `SHA-256(packet_type || generation_id || shared_iv)` omits the leading byte (0x30/0x31) that distinguishes client-originated vs server-originated packets. This is a minor but technically inaccurate omission.
|
||
|
||
**Error 2: Packet ID mixing placement is correct but could be clearer.**
|
||
|
||
The doc correctly states `key[0] ^= (packet_id >> 8)`, `key[1] ^= (packet_id & 0xff)`. This is applied *after* key derivation, not as part of it. The doc's placement in the list is fine.
|
||
|
||
**Error 3: Shared IV computation — "shared_mac = SHA-1(shared_iv)[..8]" is correct.**
|
||
|
||
Confirmed from `compute_iv_mac` in `algorithms.rs`. The doc is accurate here.
|
||
|
||
### Missing Items
|
||
|
||
- **No mention of `tsproto` dependency.** The doc lists crates used by Chanora but `tsclientlib` depends on `tsproto` internally. While Chanora doesn't directly depend on `tsproto`, it could be worth noting as an indirect dependency.
|
||
- **No mention of `tsproto-structs`.** This crate exists in the monorepo but is not used by Chanora. Could note it for completeness.
|
||
- **`hickory-proto`/`hickory-resolver` versions not specified.** The doc lists these as dependencies but doesn't note they are version 0.24.
|
||
|
||
### Structure
|
||
|
||
Excellent. Clear sections for Architecture, Protocol Details, Cryptography, and the Chanora-specific integration section is particularly valuable. The dependency chain diagram is useful.
|
||
|
||
### Verdict: **Very Good** — Highly accurate with minor encryption description inaccuracy.
|
||
|
||
---
|
||
|
||
## 3. yatqa-en.md
|
||
|
||
### Accuracy
|
||
|
||
The content appears to be sourced from https://yat.qa/ and translated/adapted. Key claims:
|
||
|
||
| Claim | Verdict | Notes |
|
||
|-------|---------|-------|
|
||
| YaTQA stands for "Yet Another TeamSpeak³ Query Admin Tool" | ✅ Matches yat.qa |
|
||
| Author: Janni "Яedeemer" K. | ✅ Matches yat.qa |
|
||
| Written in Delphi 2009, 50,000+ lines | ⚠️ Unverifiable | Claimed on yat.qa, cannot independently confirm |
|
||
| Development started April 10, 2011 | ✅ Matches yat.qa |
|
||
| First release June 29, 2011 | ✅ Matches yat.qa |
|
||
| Free freeware, no adware/spyware | ✅ Matches yat.qa |
|
||
| Windows XP+, Linux via Wine | ✅ Matches yat.qa |
|
||
| Supported servers: TS 3.9.0–3.13.7, TeaSpeak 1.4.10-beta | ⚠️ Version range may be outdated | Version range from v3.9.9b (Mar 2023) |
|
||
| Version: v3.9.9b (01 Mar 2023) | ✅ Matches yat.qa changelog |
|
||
|
||
### Missing Items
|
||
|
||
- **No mention of recent updates.** The doc states v3.9.9b from March 2023. If there have been newer releases, this could be outdated.
|
||
- **No screenshots or visual examples.** For a GUI tool, this is understandable for a text doc but worth noting.
|
||
|
||
### Factual Errors
|
||
|
||
None found. All claims align with the yat.qa website.
|
||
|
||
### Structure
|
||
|
||
Well-organized with clear sections for Features, Architecture, Configuration, System Requirements, Key Concepts, and Known Limitations. The feature categorization (General, Console, SSH Tunnel, Instance, Virtual Server) is logical.
|
||
|
||
### Verdict: **Good** — Accurate reference. Consider adding update cadence notes.
|
||
|
||
---
|
||
|
||
## 4. yatqa-de.md
|
||
|
||
### Accuracy
|
||
|
||
Same content as yatqa-en.md, translated to German. All verifiable claims match.
|
||
|
||
### EN vs DE Content Comparison
|
||
|
||
| Section | EN | DE | Match |
|
||
|---------|----|----|-------|
|
||
| Overview | ✅ | ✅ | ✅ Identical content |
|
||
| Features (all subsections) | ✅ | ✅ | ✅ Identical items |
|
||
| Supported Image Formats | ✅ | ✅ | ✅ Identical table |
|
||
| Architecture/How It Works | ✅ | ✅ | ✅ Identical |
|
||
| Configuration | ✅ | ✅ | ✅ Identical settings |
|
||
| Startup Parameters | ✅ | ✅ | ✅ Identical parameters |
|
||
| System Requirements | ✅ | ✅ | ✅ Identical |
|
||
| Key Concepts | ✅ | ✅ | ✅ Identical concepts |
|
||
| Known Limitations | ✅ | ✅ | ✅ Identical |
|
||
| IPv6 Support | ✅ | ✅ | ✅ Identical |
|
||
| Project History | ✅ | ✅ | ✅ Identical dates |
|
||
| Global Hotkeys | ✅ | ✅ | ✅ Identical shortcuts |
|
||
| Resources | ✅ | ✅ | ✅ Identical links |
|
||
| Translation | ✅ | ✅ | ✅ Identical |
|
||
|
||
**The two documents cover exactly the same content.** No sections are missing from either version.
|
||
|
||
### Minor Translation Notes
|
||
|
||
- "Ghost Mode" → "Geist-Modus" (correct)
|
||
- "Badges" → "Abzeichen" (correct)
|
||
- "Pie Chart Styles" → "Kreisdiagramm-Styles" (correct)
|
||
- Hotkeys correctly adapted: "Ctrl" → "Strg" where applicable
|
||
- Resources section: DE version links to German-specific URLs where available (`/funktionen/`, `/haeufige-fragen/`, `/unterstuetzung/`, `/ressourcen/`, `/ueber/`) — correct
|
||
|
||
### Verdict: **Good** — Accurate translation, full content parity with EN version.
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
| Document | Accuracy | Completeness | Structure | Overall |
|
||
|----------|----------|--------------|-----------|---------|
|
||
| teaspeak-overview.md | ✅ Good | ⚠️ Missing license, status | ✅ Good | **B+** |
|
||
| respeak-overview.md | ✅ Very Good | ✅ Complete | ✅ Excellent | **A-** |
|
||
| yatqa-en.md | ✅ Good | ✅ Complete | ✅ Good | **A-** |
|
||
| yatqa-de.md | ✅ Good | ✅ Complete | ✅ Good | **A-** |
|
||
|
||
### Recommended Actions
|
||
|
||
1. **teaspeak-overview.md**: Add project license, last-commit date or activity status, and note WebRTC/video capabilities.
|
||
2. **respeak-overview.md**: Fix the encryption algorithm description to include the leading 0x30/0x31 byte in the key derivation buffer. Minor — the rest is accurate.
|
||
3. **yatqa-en.md / yatqa-de.md**: No changes needed. Consider periodic re-sync to check for version updates beyond v3.9.9b.
|