← Docs hub

A2A Global Wiki Operations

이 문서는 현재 A2A Wiki가 어디에 저장되고, 여러 Codex 창에서 어떻게 공유되며, 변경 후 웹 페이지에 반영하려면 무엇을 해야 하는지 정리한다.

1. 현재 전역 저장 위치

현재 위키는 사용자 계정 silogood 기준 전역 작업 저장소처럼 사용한다.

/home/silogood/.local/share/llm-wiki-pratiyush

현재 실행 파일도 사용자 전역 PATH에 잡혀 있다.

/home/silogood/.local/bin/llmwiki

새 shell/Codex 창에서 공통으로 쓰는 환경 변수도 ~/.bashrc에 등록했다.

export LLMWIKI_HOME="$HOME/.local/share/llm-wiki-pratiyush"
export LLMWIKI_A2A_DOCS="$LLMWIKI_HOME/docs/a2a"
export LLMWIKI_URL="http://127.0.0.1:8767/docs/a2a/"
alias llmwiki-a2a='cd "$LLMWIKI_A2A_DOCS"'
alias llmwiki-rebuild='cd "$LLMWIKI_HOME" && /home/silogood/.local/bin/llmwiki build && /home/silogood/.local/bin/llmwiki lint'

~/.codex/config.toml에는 아래 marketplace 설정이 존재한다.

[marketplaces.llm-wiki]
source_type = "git"
source = "https://github.com/nvk/llm-wiki.git"

따라서 “llmwiki가 이 사용자 계정에서 전역적으로 설치되어 있고, 같은 저장소를 기준으로 build/lint/serve할 수 있는가”에 대한 답은 예다.

주요 하위 경로:

즉, 다른 Codex 창에서도 같은 사용자와 같은 filesystem을 쓰면 이 저장소를 읽고 수정할 수 있다.

2. 현재 브라우저 URL

현재 검증된 fallback 서버는 아래 주소다.

http://127.0.0.1:8767/
http://127.0.0.1:8767/docs/a2a/

대표 진입점:

http://127.0.0.1:8767/docs/a2a/executive-summary.html
http://127.0.0.1:8767/docs/a2a/book-roadmap.html
http://127.0.0.1:8767/docs/a2a/role-based-reader-paths.html

3. 다른 Codex 창에서 업데이트되는 방식

다른 Codex 창에서 이 위키를 업데이트할 수 있다. 단, 자동 실시간 반영은 아니다.

정리하면:

문서 수정 -> llmwiki build -> 브라우저 새로고침

중요한 구분:

즉 현재는 전역 저장소 + 전역 실행 도구 + 전역 AGENTS 운영 규칙 + 수동 build/lint 갱신 상태다.
“완전 자동 동기화 시스템”은 아니지만, 새 Codex 창이 전역 AGENTS.md를 읽는 한 A2A 관련 작업에서는 이 위키를 기준 지식 저장소로 참조하도록 설정되어 있다.

4. Codex 전역 설정 확인 결과

확인 기준:

/home/silogood/.codex/config.toml
/home/silogood/.codex/AGENTS.md
/home/silogood/.bashrc
/home/silogood/.local/bin/llmwiki
/home/silogood/.local/share/llm-wiki-pratiyush

현재 ~/.codex/AGENTS.md에는 skill 사용, multi-agent, verification, browser 사용 규칙과 함께 llmwiki 운영 규칙이 들어 있다.

핵심 규칙:

A2A, 온디바이스 bridge, DeviceAgent, SoC TaskManager, 메모리/개인화, 업체 전달 관련 작업은
/home/silogood/.local/share/llm-wiki-pratiyush/docs/a2a 를 먼저 검색/확인한다.

새로 확정된 구조, API 계약, 테스트 증거, 업체 요구사항, 아키텍처 결정은 llmwiki에 기록한다.

문서 수정 후 /home/silogood/.local/bin/llmwiki build 와
/home/silogood/.local/bin/llmwiki lint 를 실행한다.

현재 ~/.bashrc에는 아래 값도 들어 있다.

LLMWIKI_HOME=/home/silogood/.local/share/llm-wiki-pratiyush
LLMWIKI_A2A_DOCS=/home/silogood/.local/share/llm-wiki-pratiyush/docs/a2a
LLMWIKI_URL=http://127.0.0.1:8767/docs/a2a/

따라서 다른 Codex 창도 새로 시작하면 같은 저장소를 기준으로 참조/업데이트하는 운영 지침을 받는다. 다만 이미 떠 있는 기존 Codex 창은 시작 시점에 읽은 지침을 계속 사용할 수 있으므로, 확실히 반영하려면 새 창/새 세션에서 시작하는 것이 안전하다.

5. 표준 갱신 절차

다른 Codex 창에서 위키를 수정했다면 아래 순서를 따른다.

cd /home/silogood/.local/share/llm-wiki-pratiyush
/home/silogood/.local/bin/llmwiki build
/home/silogood/.local/bin/llmwiki lint
curl --max-time 3 -I http://127.0.0.1:8767/docs/a2a/

기대 결과:

llmwiki build: build complete
llmwiki lint: 0 errors, 0 warnings
HTTP/1.0 200 OK

6. 서버가 내려갔을 때

현재 fallback 정적 서버는 site/ 디렉터리를 서빙한다. 내려갔다면 아래처럼 다시 띄운다.

cd /home/silogood/.local/share/llm-wiki-pratiyush/site
python3 -m http.server 8767 --bind 0.0.0.0

확인:

curl --max-time 3 -I http://127.0.0.1:8767/docs/a2a/

7. 동시 작업 충돌 주의

여러 Codex 창이 같은 파일을 동시에 수정하면 마지막 저장이 이전 변경을 덮을 수 있다.

안전한 운영 원칙:

• 큰 구조 변경은 한 창에서만 진행한다.
• 다른 창에서는 수정 전에 대상 파일을 다시 읽는다.
• 같은 문서를 동시에 고치지 않는다.
• 변경 후 rg로 새 링크가 들어갔는지 확인한다.
• 마무리마다 llmwiki build, llmwiki lint, 주요 URL curl -I를 실행한다.

충돌 위험이 큰 파일:

docs/a2a/index.md
docs/a2a/book-roadmap.md
docs/a2a/architecture-diagrams.md
docs/a2a/documentation-quality-audit.md

이 파일들은 거의 모든 새 문서가 연결되는 허브 역할이므로 동시에 수정하지 않는 것이 좋다.

8. 다른 Codex 창에서 시작할 때 체크리스트

다른 창에서 이어서 작업할 때 먼저 확인한다.

test -d /home/silogood/.local/share/llm-wiki-pratiyush
test -f /home/silogood/.local/share/llm-wiki-pratiyush/docs/a2a/index.md
curl --max-time 3 -I http://127.0.0.1:8767/docs/a2a/

그 다음 현재 상태를 본다.

cd /home/silogood/.local/share/llm-wiki-pratiyush
rg -n "A2A Executive Summary|A2A Role-Based Reader Paths|A2A Evidence Index" docs/a2a

9. 전역 강제 운영 규칙

모든 Codex 창에서 llmwiki를 사실상 표준 지식 저장소로 쓰기 위해 ~/.codex/AGENTS.md에 아래 운영 규칙을 추가했다.

## LLM Wiki Operating Rule

- A2A, 온디바이스, DeviceAgent, SoC TaskManager, 메모리/개인화 관련 작업을 시작하면 먼저 `/home/silogood/.local/share/llm-wiki-pratiyush/docs/a2a`를 검색한다.
- 새로 확정된 구조, 계약, 테스트 결과, 업체 전달사항은 같은 wiki root에 문서화한다.
- 문서 수정 후 `/home/silogood/.local/bin/llmwiki build`와 `/home/silogood/.local/bin/llmwiki lint`를 실행한다.
- 같은 허브 문서를 여러 Codex 창에서 동시에 수정하지 않는다.

이 규칙으로 다른 Codex 창도 AGENTS.md를 읽는 범위에서는 llmwiki를 더 일관되게 참조하게 된다. 단, 이것도 “자동 동기화 시스템”이 아니라 Codex 운영 지침이다.

10. 현재 운영 판정

현재 위키는 아래 상태로 운영한다.

11. Cloudflare Pages 배포 상태

현재 팀 공유용 curated wiki는 Cloudflare Pages에 배포한다.

즉시 배포 명령:

cd /home/silogood/.local/share/llm-wiki-pratiyush
CF_PAGES_PROJECT=sk-intellix-wiki bash ops/wiki-deployment/deploy-cloudflare-pages-if-changed.sh

이 명령은 아래를 한 번에 수행한다.

llmwiki build
llmwiki lint
curated stage 생성
sensitive scan
변경 hash 비교
Cloudflare Pages deploy
deploy-state hash 저장

최근 확인된 배포 결과:

llmwiki build: 성공
llmwiki lint: 0 errors, 0 warnings
curated stage: /tmp/sk-intellix-wiki-stage, 124 files
sensitive scan: passed
Cloudflare Pages project: sk-intellix-wiki
deployment preview: https://9195e606.sk-intellix-wiki.pages.dev
team-facing entrypoint: https://sk-intellix-wiki.pages.dev/docs/sk-intellix/

12. 관련 문서

• Local Access Guide
• A2A Executive Summary
• Book Roadmap
• Documentation Quality Audit