docs: fix documentation issues found during newbie testing

docs-site/content/docs/en/contributing/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Contributing",
-  "pages": ["index", "development", "testing", "code-style"]
+  "pages": ["index", "development", "testing", "code-style", "pull-requests"]
 }

docs-site/content/docs/en/contributing/pull-requests.mdx

@@ -0,0 +1,130 @@
+---
+title: Pull Requests
+description: Guidelines for submitting pull requests to Bingsan
+---
+
+# Pull Requests
+
+This guide covers the process for submitting pull requests to Bingsan.
+
+## Before You Start
+
+1. **Check existing issues** - Look for related issues or discussions
+2. **Open an issue first** - For significant changes, discuss the approach before coding
+3. **Fork the repository** - Create your own fork to work on
+
+## Creating a Pull Request
+
+### 1. Create a Branch
+
+```bash
+# Sync your fork
+git fetch upstream
+git checkout main
+git merge upstream/main
+
+# Create a feature branch
+git checkout -b feature/your-feature-name
+```
+
+Use descriptive branch names:
+- `feature/add-gcs-support` - New features
+- `fix/namespace-deletion-bug` - Bug fixes
+- `docs/update-api-reference` - Documentation
+- `refactor/simplify-auth-flow` - Code refactoring
+
+### 2. Make Your Changes
+
+- Follow the [Code Style Guide](/docs/contributing/code-style)
+- Write tests for new functionality
+- Update documentation as needed
+
+### 3. Commit Your Changes
+
+Write clear, descriptive commit messages:
+
+```bash
+# Good
+git commit -m "Add GCS storage backend support"
+git commit -m "Fix race condition in namespace deletion"
+
+# Bad
+git commit -m "fix bug"
+git commit -m "update"
+```
+
+### 4. Run Tests and Lints
+
+Before submitting, ensure all checks pass:
+
+```bash
+# Run linter
+make lint
+
+# Run tests
+make test
+
+# Run integration tests (if applicable)
+make test-integration
+```
+
+### 5. Push and Create PR
+
+```bash
+git push origin feature/your-feature-name
+```
+
+Then open a pull request on GitHub.
+
+## Pull Request Guidelines
+
+### Title
+
+Use a clear, descriptive title:
+- `Add: GCS storage backend support`
+- `Fix: Race condition in namespace deletion`
+- `Docs: Update API reference for tables endpoint`
+
+### Description
+
+Include in your PR description:
+- **What** - Brief summary of changes
+- **Why** - Motivation and context
+- **How** - Implementation approach (if complex)
+- **Testing** - How you tested the changes
+
+### Checklist
+
+Before requesting review:
+
+- [ ] Code follows project style guidelines
+- [ ] Tests pass locally (`make test`)
+- [ ] Linter passes (`make lint`)
+- [ ] Documentation updated (if applicable)
+- [ ] Commit messages are clear and descriptive
+
+## Review Process
+
+1. **Automated checks** - CI runs tests and lints
+2. **Code review** - Maintainers review your code
+3. **Address feedback** - Make requested changes
+4. **Merge** - Once approved, a maintainer will merge
+
+### Responding to Feedback
+
+- Be responsive to review comments
+- Ask for clarification if feedback is unclear
+- Push additional commits to address feedback (don't force-push)
+
+## After Merge
+
+- Delete your feature branch
+- Sync your fork with upstream
+- Celebrate your contribution!
+
+## Getting Help
+
+If you need help with your PR:
+- Comment on the PR with questions
+- Join discussions in GitHub Issues
+- Check existing PRs for examples

docs-site/content/docs/en/getting-started/first-steps.mdx

@@ -59,6 +59,27 @@ curl -X POST http://localhost:8181/v1/namespaces \
   }'
 ```
 
+### Referencing Nested Namespaces in URLs
+
+When referencing nested namespaces in REST API URLs (GET, DELETE, HEAD), use one of these formats:
+
+**Option 1: Dot-separated (simple)**
+```bash
+# Get nested namespace
+curl http://localhost:8181/v1/namespaces/analytics.events
+
+# Delete nested namespace
+curl -X DELETE http://localhost:8181/v1/namespaces/analytics.events
+```
+
+**Option 2: URL-encoded unit separator (`%1F`)**
+```bash
+# For namespaces with dots in their names, use %1F separator
+curl http://localhost:8181/v1/namespaces/analytics%1Fevents
+```
+
+> **Note**: Use `%1F` (unit separator) when namespace parts contain dots, e.g., `["my.app", "events"]` should be encoded as `my.app%1Fevents`.
+
 ## List Namespaces
 
 ```bash

docs-site/content/docs/en/getting-started/installation.mdx

@@ -36,7 +36,7 @@ Build and run Bingsan directly on your machine.
 
 ### Prerequisites
 
-- Go 1.25 or later
+- Go 1.24 or later
 - PostgreSQL 15+ (running and accessible)
 
 ### Steps
@@ -87,11 +87,15 @@ GOOS=darwin GOARCH=arm64 go build -o bin/iceberg-catalog-darwin-arm64 ./cmd/iceb
 
 ## Method 3: Docker Image
 
-Pull and run the pre-built Docker image.
+Build and run the Docker image locally.
 
 ```bash
-# Pull the image
-docker pull ghcr.io/kimuyb/bingsan:latest
+# Clone the repository
+git clone https://github.com/teamPaprika/bingsan.git
+cd bingsan
+
+# Build the image
+docker build -t bingsan:latest -f deployments/docker/Dockerfile .
 
 # Run with environment variables
 docker run -d \
@@ -102,9 +106,11 @@ docker run -d \
   -e ICEBERG_DATABASE_USER=iceberg \
   -e ICEBERG_DATABASE_PASSWORD=iceberg \
   -e ICEBERG_DATABASE_DATABASE=iceberg_catalog \
-  ghcr.io/kimuyb/bingsan:latest
+  bingsan:latest
 ```
 
+> **Note**: Make sure PostgreSQL is accessible from the container. For local development, use Method 1 (Docker Compose) which handles networking automatically.
+
 ## Method 4: Kubernetes
 
 Deploy to Kubernetes using Helm or raw manifests.

docs-site/content/docs/en/getting-started/quick-start.mdx

@@ -38,6 +38,7 @@ docker compose -f deployments/docker/docker-compose.yml up -d
 This starts:
 - **Bingsan** - REST catalog server on port 8181
 - **PostgreSQL** - Metadata database on port 5432
+- **MinIO** - S3-compatible object storage on ports 9000 (API) and 9001 (Console)
 
 ## Step 4: Verify Installation
 
@@ -49,7 +50,7 @@ curl http://localhost:8181/health
 
 Expected response:
 ```json
-{"status": "ok"}
+{"status": "healthy"}
 ```
 
 Check readiness (includes database connectivity):
@@ -60,7 +61,7 @@ curl http://localhost:8181/ready
 
 Expected response:
 ```json
-{"status": "ready", "database": "connected"}
+{"status": "ready", "checks": {"database": "healthy"}}
 ```
 
 ## Step 5: Create Your First Namespace

docs-site/content/docs/ko/contributing/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "기여하기",
-  "pages": ["index", "development", "testing", "code-style"]
+  "pages": ["index", "development", "testing", "code-style", "pull-requests"]
 }

docs-site/content/docs/ko/contributing/pull-requests.mdx

@@ -0,0 +1,130 @@
+---
+title: Pull Request
+description: Bingsan에 Pull Request 제출 가이드
+---
+
+# Pull Request
+
+Bingsan에 Pull Request를 제출하는 과정을 안내합니다.
+
+## 시작하기 전에
+
+1. **기존 이슈 확인** - 관련 이슈나 논의가 있는지 확인
+2. **먼저 이슈 열기** - 중요한 변경사항은 코딩 전에 접근 방식 논의
+3. **저장소 포크** - 작업할 자신만의 포크 생성
+
+## Pull Request 만들기
+
+### 1. 브랜치 생성
+
+```bash
+# 포크 동기화
+git fetch upstream
+git checkout main
+git merge upstream/main
+
+# 기능 브랜치 생성
+git checkout -b feature/your-feature-name
+```
+
+설명적인 브랜치 이름 사용:
+- `feature/add-gcs-support` - 새 기능
+- `fix/namespace-deletion-bug` - 버그 수정
+- `docs/update-api-reference` - 문서
+- `refactor/simplify-auth-flow` - 코드 리팩토링
+
+### 2. 변경사항 작성
+
+- [코드 스타일 가이드](/docs/contributing/code-style) 준수
+- 새 기능에 대한 테스트 작성
+- 필요시 문서 업데이트
+
+### 3. 변경사항 커밋
+
+명확하고 설명적인 커밋 메시지 작성:
+
+```bash
+# 좋은 예
+git commit -m "Add GCS storage backend support"
+git commit -m "Fix race condition in namespace deletion"
+
+# 나쁜 예
+git commit -m "fix bug"
+git commit -m "update"
+```
+
+### 4. 테스트 및 린트 실행
+
+제출 전 모든 검사 통과 확인:
+
+```bash
+# 린터 실행
+make lint
+
+# 테스트 실행
+make test
+
+# 통합 테스트 실행 (해당되는 경우)
+make test-integration
+```
+
+### 5. 푸시 및 PR 생성
+
+```bash
+git push origin feature/your-feature-name
+```
+
+그런 다음 GitHub에서 Pull Request를 엽니다.
+
+## Pull Request 가이드라인
+
+### 제목
+
+명확하고 설명적인 제목 사용:
+- `Add: GCS storage backend support`
+- `Fix: Race condition in namespace deletion`
+- `Docs: Update API reference for tables endpoint`
+
+### 설명
+
+PR 설명에 포함할 내용:
+- **What** - 변경사항 요약
+- **Why** - 동기와 컨텍스트
+- **How** - 구현 접근 방식 (복잡한 경우)
+- **Testing** - 테스트 방법
+
+### 체크리스트
+
+리뷰 요청 전:
+
+- [ ] 코드가 프로젝트 스타일 가이드라인 준수
+- [ ] 로컬에서 테스트 통과 (`make test`)
+- [ ] 린터 통과 (`make lint`)
+- [ ] 문서 업데이트됨 (해당되는 경우)
+- [ ] 커밋 메시지가 명확하고 설명적임
+
+## 리뷰 프로세스
+
+1. **자동화된 검사** - CI가 테스트와 린트 실행
+2. **코드 리뷰** - 메인테이너가 코드 검토
+3. **피드백 반영** - 요청된 변경사항 반영
+4. **병합** - 승인되면 메인테이너가 병합
+
+### 피드백에 응답하기
+
+- 리뷰 코멘트에 신속하게 응답
+- 피드백이 불명확하면 명확화 요청
+- 피드백 반영을 위해 추가 커밋 푸시 (force-push 하지 않기)
+
+## 병합 후
+
+- 기능 브랜치 삭제
+- upstream과 포크 동기화
+- 기여를 축하하세요!
+
+## 도움 받기
+
+PR에 도움이 필요하면:
+- PR에 질문 코멘트 달기
+- GitHub Issues에서 논의 참여
+- 기존 PR을 예시로 확인

docs-site/content/docs/ko/getting-started/first-steps.mdx

@@ -59,6 +59,27 @@ curl -X POST http://localhost:8181/v1/namespaces \
   }'
 ```
 
+### URL에서 중첩 네임스페이스 참조하기
+
+REST API URL (GET, DELETE, HEAD)에서 중첩 네임스페이스를 참조할 때 다음 형식 중 하나를 사용합니다:
+
+**옵션 1: 점으로 구분 (간단)**
+```bash
+# 중첩 네임스페이스 조회
+curl http://localhost:8181/v1/namespaces/analytics.events
+
+# 중첩 네임스페이스 삭제
+curl -X DELETE http://localhost:8181/v1/namespaces/analytics.events
+```
+
+**옵션 2: URL 인코딩된 유닛 구분자 (`%1F`)**
+```bash
+# 네임스페이스 이름에 점이 포함된 경우 %1F 구분자 사용
+curl http://localhost:8181/v1/namespaces/analytics%1Fevents
+```
+
+> **참고**: 네임스페이스 부분에 점이 포함된 경우 `%1F` (유닛 구분자)를 사용하세요. 예: `["my.app", "events"]`는 `my.app%1Fevents`로 인코딩합니다.
+
 ## 네임스페이스 목록 조회
 
 ```bash