Skip to content

Commit 41f70dc

Browse files
tonyHu08tonyHu08
committed
docs: improve onboarding + issue templates
1 parent 7cd62f7 commit 41f70dc

7 files changed

Lines changed: 164 additions & 3 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: Bug report
2+
description: Something isn't working as expected.
3+
title: "[Bug]: "
4+
labels: ["bug"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for reporting! Please don't paste secrets (Telegram bot tokens, API keys, etc.).
10+
- type: dropdown
11+
id: platform
12+
attributes:
13+
label: Platform
14+
options:
15+
- macOS (Apple Silicon)
16+
- macOS (Intel)
17+
validations:
18+
required: true
19+
- type: input
20+
id: app_version
21+
attributes:
22+
label: App version
23+
placeholder: e.g. v0.1.3
24+
validations:
25+
required: true
26+
- type: textarea
27+
id: what_happened
28+
attributes:
29+
label: What happened?
30+
description: What did you expect, and what actually happened?
31+
validations:
32+
required: true
33+
- type: textarea
34+
id: steps
35+
attributes:
36+
label: Steps to reproduce
37+
description: Minimal steps so we can reproduce it.
38+
placeholder: |
39+
1. Open the app...
40+
2. In Telegram, send /threads...
41+
3. ...
42+
validations:
43+
required: true
44+
- type: textarea
45+
id: logs
46+
attributes:
47+
label: Logs (optional)
48+
description: Paste the last ~200 lines from the app "Logs & Feedback" page, with secrets removed.
49+
render: text
50+

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Questions / Help
4+
url: https://github.com/tonyHu08/CodeX_Bridge/discussions
5+
about: Please ask and answer questions here (if Discussions is enabled).
6+
- name: Security report
7+
url: https://github.com/tonyHu08/CodeX_Bridge/security/policy
8+
about: Please report security issues privately.
9+

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Feature request
2+
description: Suggest an idea or improvement.
3+
title: "[Feature]: "
4+
labels: ["enhancement"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Please describe the problem first, then your preferred solution.
10+
- type: textarea
11+
id: problem
12+
attributes:
13+
label: Problem
14+
description: What are you trying to achieve? What's painful today?
15+
validations:
16+
required: true
17+
- type: textarea
18+
id: proposal
19+
attributes:
20+
label: Proposed solution
21+
description: What should the product do?
22+
validations:
23+
required: true
24+
- type: textarea
25+
id: alternatives
26+
attributes:
27+
label: Alternatives considered (optional)
28+
description: Any alternatives you tried or considered.
29+

‎.github/pull_request_template.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
## Summary
2+
3+
- What does this PR change?
4+
5+
## Checklist
6+
7+
- [ ] I tested this change locally
8+
- [ ] I updated docs/screenshots if needed
9+
- [ ] I did not include secrets (tokens/keys) in code or screenshots
10+

‎README.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Control your local Codex threads from Telegram. Keep working while away from you
1111

1212
[English](#english) | [中文](#中文)
1313

14-
Quick links: [Download](https://github.com/tonyHu08/CodeX_Bridge/releases) · [Commands](./docs/COMMANDS.md) · [Troubleshooting](./docs/TROUBLESHOOTING.md) · [Report issue](https://github.com/tonyHu08/CodeX_Bridge/issues)
14+
Quick links: [Download](https://github.com/tonyHu08/CodeX_Bridge/releases) · [Commands](./docs/COMMANDS.md) · [FAQ](./docs/FAQ.md) · [Troubleshooting](./docs/TROUBLESHOOTING.md) · [Press kit](./assets/press-kit/README.md) · [Report issue](https://github.com/tonyHu08/CodeX_Bridge/issues)
1515

1616
---
1717

@@ -112,6 +112,13 @@ flowchart TB
112112
- [Threat model](./docs/THREAT_MODEL.md)
113113
- [Self-hosting](./docs/SELF_HOSTING.md)
114114
- [Troubleshooting](./docs/TROUBLESHOOTING.md)
115+
- [FAQ](./docs/FAQ.md)
116+
117+
### Help this project grow 💡
118+
119+
- Star the repo if it helped you.
120+
- Share a screenshot or a short clip: pairing → `/threads` → first reply.
121+
- If you write a post/video about it, open a PR to add it to the README.
115122

116123
### Development
117124

‎docs/FAQ.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# FAQ
2+
3+
## Is this just message forwarding?
4+
5+
No. Codex Bridge binds to a **real Codex thread** on your Mac (via Codex App Server), so context stays consistent.
6+
7+
## What do I need to install?
8+
9+
- Codex App (installed + logged in)
10+
- Codex Bridge Desktop (this project)
11+
- Telegram
12+
13+
No Node/Homebrew is required for end users.
14+
15+
## Does it read my prompts/files?
16+
17+
Codex Bridge only receives what you send to the Telegram bot, and forwards it to your local Codex thread.
18+
19+
Please review:
20+
21+
- [Privacy](./PRIVACY.md)
22+
- [Threat model](./THREAT_MODEL.md)
23+
24+
## Why do I still see approvals in Telegram?
25+
26+
Because your Telegram message can trigger actions that modify files or run commands.
27+
28+
Approvals are a **safety boundary**: you can confirm or deny from anywhere.
29+
30+
## Can it show per-thread “busy” status?
31+
32+
Not reliably today.
33+
34+
Codex Bridge can only observe tasks that **it started itself**. Codex currently does not expose a stable “thread is running” signal for arbitrary threads.
35+
36+
## Can it send/receive images?
37+
38+
Photo input is experimental and depends on your Codex App / App Server version.
39+
40+
If it works on your machine, you'll be able to send a Telegram photo and let Codex see it as an input image.
41+
42+
## Why does `/threads` sometimes degrade?
43+
44+
When `thread/list` is slow or unavailable, `/threads` falls back to the local Codex sidebar cache.
45+
46+
That keeps the bot responsive, but some fields (like timestamps) may be missing.
47+

‎docs/LAUNCH_PLAYBOOK.md‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,12 @@ This playbook helps you launch Codex Bridge in English and Chinese channels in o
1414
## 2. Launch assets checklist
1515

1616
- App download link (latest release).
17-
- 30-second demo GIF/video.
17+
- 30-second demo GIF/video (pairing → `/threads` → first reply).
1818
- 3 screenshots:
1919
- onboarding,
2020
- `/threads` binding in Telegram,
2121
- approval + final response.
22+
- Press kit (ready-to-use): `assets/press-kit/`
2223
- README link.
2324
- Privacy note: anonymous metrics only; no message content collected.
2425

@@ -52,7 +53,15 @@ CTA：
5253
- Thursday: Chinese tutorial post + practical case.
5354
- Weekend: user story recap and feedback highlights.
5455

55-
## 5. Comment/reply templates
56+
## 5. Launch day checklist (30 min)
57+
58+
1. Make sure the latest Release has DMG + ZIP + screenshots in notes.
59+
2. Update README first screen (value + screenshots + 2-minute setup).
60+
3. Prepare 1 short clip and 3 screenshots from `assets/press-kit/`.
61+
4. Post in 1 EN channel + 1 ZH channel the same day.
62+
5. Stay online for 2 hours to answer comments (pairing failures, `/threads` tips).
63+
64+
## 6. Comment/reply templates
5665

5766
- EN:
5867
- `If pairing fails, click "Refresh pairing status" in app and send /start again in Telegram.`

0 commit comments

Comments
 (0)