refactor: restructure docs as submodule, add dev-docs/ and AGENTS.md
- 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)
This commit is contained in:
Edison Jwa
@@ -0,0 +1,193 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user