Report errors and propose improvements for SpoonOS docs/configs

[MasteraSnackin]

---

name: Documentation & Codebase Review
about: Report errors and propose improvements for SpoonOS docs/configs
labels: documentation, bug, improvement assignees: ''

---

Summary

Describe the issue in one or two sentences.
E.g.: Several critical documentation files are missing or inconsistent, causing confusion during installation and configuration.

Major Documentation Issues

• Broken links:

  • doc/mcp_mode_usage.md missing (404 error)
  • docs/agent_configuration.md missing

• Python version confusion:

  • README: "Python 3.11+"
  • Installation guide: "Python ≥ 3.10"

• Quick Installation unclear for Windows users:

  • Windows instructions present in installation.md but not referenced in README

• Unreferenced features:

  • "Enhanced Graph System" and "Prompt Caching" lack deep-links/context

• Markdown code block issues:

  • Code examples lack syntax highlighting, correct formatting, or contain copy-paste errors

• Missing GitHub About section:

  • No project description or tags

Specific Errors & Config Conflicts

• Config naming is inconsistent:

  • "agents" vs. "agents"
  • "class" vs. "agent_class"
  • "tools" vs. "tool_configs"
  • Deprecated tool names in examples (e.g., “crypto_powerdata_cex” vs. “crypto_tools”)
  • Example fields missing (e.g., "exchange": "binance")

• Unlinked/404 guides:

  • "Complete Graph System Guide" lacks link in README and doc/graph_agent.md

• CLI Troubleshooting section missing from README

• Security practices only generically mentioned (no actionable checklist)

Recommended Fixes

• Add and link all missing documentation files (doc/mcp_mode_usage.md, docs/agent_configuration.md).
• Standardize Python version requirements in all guides.
• Clarify/clean up config examples, remove deprecated field names.
• Ensure referenced features in README have deep links or context.
• Improve formatting for shell and Python code blocks, enable easy copy-paste.
• Add a project description and tags to the GitHub About section.
• Reference Windows install steps from README.
• Center troubleshooting & best practices in README with links to detailed guides.
• Create a security checklist section.

---

name: Documentation & Configuration Fixes
about: Track major documentation fixes and configuration consistency updates for SpoonOS
title: "Docs & Config Update: [brief summary]"
labels: documentation, enhancement
assignees: ''

---

🟠 Major Documentation Fixes

Restore Missing Docs

• Add or restore doc/mcp_mode_usage.md and validate all linked references in README, agent.md, and other guides.
• Add or restore doc/agent_configuration.md (used in agent.md and examples/).

Project Description

• Add a concise project summary in the GitHub "About" section.
• Add relevant tags/topics (e.g., AI agents, Web3, CLI tools, Python).

Python Version Consistency

• Standardize required Python version across README, installation.md, and .env.example (e.g., 3.10+ or 3.11+).

Cross-Link Deep Dives

• Fix or add deep links for all feature references in README (e.g., “Enhanced Graph System”, “Prompt Caching”, “Unified LLM Architecture”).
• Provide summaries or short feature explanations with links to detailed guides.

Fix Unescaped Code Blocks

• Review shell and Python examples:
  • Remove unnecessary $ and indentation.
  • Add proper syntax highlighting (``````python, etc.).
  • Remove “Copy” / “CopyPrefer” elements for easier command copying.

Document Windows Installation

• In README and installation.md, explicitly document Windows installation, prerequisites, and activation instructions.

---

🟡 Configuration and Examples

Unify Config Key Names

• Use consistent keys across all configuration examples (class, name, tools, etc.).
• Remove deprecated or mismatched fields.
• Verify all field names reflect the current source code.

Update Tool Names

• Replace deprecated tool names:
  • e.g., crypto_powerdata_cex → crypto_tools (or vice versa, according to code).
• Cross-check that all tool references match the current implementation.

Agent Class Name Clarity

• Ensure config files consistently use active class names (SpoonReactAI, SpoonReactMCP, etc.).
• Correct mismatches between documentation and config templates.

Clarify MCP Example Paths

• Add notes clarifying when global installs or setup steps are required:
  e.g., npm install -g tavily-mcp
• Verify all example paths and commands work cleanly in Linux, macOS, and Windows.

---

🟢 Troubleshooting & Security

README Troubleshooting Section

• Add a Troubleshooting section summarizing:
  • Common CLI commands.
  • Frequent error patterns and fixes.
  • Deep links to related doc/cli.md sections.

Actionable Security Checklist

Add a Security Checklist with step-by-step actions:

• Never commit API keys.
• Add .env to .gitignore.
• Use environment variables for production configuration.
• Apply strict file permissions to .env files.

---

🔵 General Improvements

Complete All Missing Deep Links

• Ensure “Full guide”, “Complete Graph System Guide”, and other referenced items have working URLs or remove them entirely.

Fill Out About, License, and Contributing

• Finalize missing repository metadata:
  • LICENSE file.
  • CONTRIBUTING.md.
  • Open-source policy description.
  • Clear guidance on submitting issues, PRs, and help requests.

---

✅ Suggested Labels

documentation, enhancement, config, security, troubleshooting

---

📎 Additional Context

Add any related references, examples, or context here (e.g., links to affected commits, config samples, or screenshots).